# Setup API Client
Source: https://docs.binarly.io/api-reference/authentication/create-api-client
Set up Machine-to-Machine (M2M) authentication for automated integrations and CI/CD pipelines.
## SaaS Customers
**Request Required** SaaS customers cannot create M2M credentials themselves. Contact [support@binarly.io](mailto:support@binarly.io) to request API credentials for your organization.
When contacting support, please provide:
* Your organization name
* Intended use case (CI/CD, automation, integration)
* Any specific permission requirements
You will receive:
* **Client ID** - Your API client identifier
* **Client Secret** - Your secure API key
* **Auth URL** - Your authentication endpoint
Once you receive your credentials, proceed to [M2M Authentication](/api-reference/authentication/get-m2m-token).
## On-Premises Customers
On-Premises customers have full access to Keycloak and can create API clients directly.
### Step 1: Navigate to Keycloak
1. Open your Keycloak Admin Console: `https:///admin`
2. Log in with your administrator credentials.
![Keycloak Login Page]()
### Step 2: Select Realm
1. Near the top-left corner, click **Manage realms**
2. Select `BinarlyRealm` from the list
![Select BinarlyRealm]()
3. Verify you are in the correct realm
![Verify BinarlyRealm]()
### Step 3: Create a Client
1. Select **Clients** from the left-hand menu.
2. Click **Create client**.
![Clients Create]()
#### General Settings
* **Client type**: OpenID Connect
* **Client ID**: Enter a descriptive ID (e.g., `api-client` or `ci-cd-automation`).
* **Name**: (Optional) Enter a friendly name.
![Create Client - General Settings]()
Click **Next**.
#### Capability Config
* **Client authentication**: **On** (This enables Client Credentials).
* **Authorization**: Off (unless specifically required).
* **Authentication flow**:
* Set **Service accounts roles** only
![Client Capability Config]()
Click **Next** and then **Save**.
### Step 4: Obtain Credentials
1. After saving, select the **Credentials** tab at the top of the client details page.
2. Copy the **Client Secret**. This is your secure key for API access.
![Client Credentials]()
Store this secret securely. If lost or compromised, regenerate it immediately using the "Regenerate" button on this page.
## Next Steps
Now that you have your Client ID and Secret, you are ready to generate an access token.
[Go to M2M Authentication ->](/api-reference/authentication/get-m2m-token)
# User Authentication
Source: https://docs.binarly.io/api-reference/authentication/generate-token
Authenticate as a user to perform ad-hoc queries or engineer-level tasks. This method requires a username (email) and password.
**Not for Automation**
This method requires a specific user's credentials and is **not recommended** for CI/CD pipelines. For automated integration, use [M2M Authentication](/api-reference/authentication/create-api-client).
**SSO Not Supported**
This authentication method does **not** work with SSO (SAML, OIDC federation). Users must have a dedicated username and password configured directly in Keycloak. This approach ties API usage to individual BTP users and respects RBAC permissions.
## Password Grant Flow
Use this flow for interactive access where you can securely provide your user credentials.
### Request
```bash Request theme={null}
# 1. Set your credentials
export BINARLY_EMAIL="your-email@example.com"
export BINARLY_PASSWORD="your-password"
# Replace {slug} with your organization's tenant identifier
export BINARLY_AUTH_URL="https://auth-{slug}.binarly.cloud/realms/BinarlyRealm/protocol/openid-connect/token"
# 2. Request the token
curl -v -s -H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=password" \
--data-urlencode "scope=openid" \
--data-urlencode "client_id=BinarlyClient" \
--data-urlencode "username=${BINARLY_EMAIL}" \
--data-urlencode "password=${BINARLY_PASSWORD}" \
"${BINARLY_AUTH_URL}"
```
### Response
The response contains the `access_token` needed for API requests.
```json theme={null}
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 1800
}
```
## Next Steps
Include this token in the `Authorization` header of your API requests:
`Authorization: Bearer `
# M2M Authentication
Source: https://docs.binarly.io/api-reference/authentication/get-m2m-token
Once you have created an API Client in Keycloak, use your credentials to obtain an access token.
**Best for Automation** Use Machine-to-Machine (M2M) authentication for **CI/CD pipelines** (Jenkins, GitHub Actions) and background services. This method supports zero-downtime credential rotation.
## Prerequisites
You need the `client_id` and `client_secret` from your [API Client Setup](/api-reference/authentication/create-api-client).
## Request Token
Use the Client Credentials Grant flow to exchange your ID and Secret for a Bearer token.
```bash Request theme={null}
# 1. Set your credentials (export them in your shell or CI/CD env)
export BINARLY_CLIENT_ID="your-client-id"
export BINARLY_CLIENT_SECRET="your-client-secret"
# Replace {slug} with your organization's tenant identifier
export BINARLY_AUTH_URL="https://auth-{slug}.binarly.cloud/realms/BinarlyRealm/protocol/openid-connect/token"
# 2. Request the token
curl -s --fail-with-body \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_id=${BINARLY_CLIENT_ID}" \
--data-urlencode "client_secret=${BINARLY_CLIENT_SECRET}" \
"${BINARLY_AUTH_URL}"
```
### Response
The API returns a JSON object containing your `access_token`.
```json theme={null}
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 1800
}
```
## Using the Token
Include the token in the `Authorization` header when making API requests:
`Authorization: Bearer `
> **Note**: Tokens expire after 30 minutes. Your automation should request a fresh token before each job or handle `401 Unauthorized` errors by refreshing credentials.
# On-Prem API Considerations
Source: https://docs.binarly.io/api-reference/deployment/onprem-considerations
API specifics for On-Premise deployments
On-Premise deployments run the Binarly Transparency Platform within your own infrastructure, providing complete control over data and connectivity.
## Base URLs
Your base URLs are determined by your installation configuration:
| Service | URL Pattern |
| ------------------------- | -------------------------------------------------- |
| API Server | `https:///api/v4` |
| Authentication (Keycloak) | `https:///realms/BinarlyRealm` |
| Dashboard | `https://` |
> Consult your infrastructure team or installation documentation for exact URLs.
## Authentication
On-Prem uses **Keycloak** as the identity provider. The setup process is identical to SaaS:
* **M2M (CI/CD)**: [Setup API Client](/api-reference/authentication/create-api-client) – Keycloak Admin Console access required
* **User Access**: [User Authentication](/api-reference/authentication/generate-token)
### Keycloak Admin Access
For On-Prem installations, you have full access to the Keycloak Admin Console to:
* Create and manage API Clients
* Configure user federation (LDAP, SAML)
* Customize authentication policies
See the [On-Prem Installation Guide](/on-prem/v3/configuration) for Keycloak configuration details.
## Network Considerations
### Internal Access
Ensure your CI/CD runners can reach:
* API Server (port 443)
* Keycloak (port 443)
### Air-Gapped Environments
For fully air-gapped deployments:
* Pre-download required container images
* Configure local image registries
* See [On-Prem Installation](/on-prem/v3/installation) for offline setup
## Differences from SaaS
| Feature | SaaS | On-Prem |
| --------------- | -------------- | --------------------- |
| Updates | Automatic | Manual (Helm upgrade) |
| Keycloak Access | Limited | Full Admin |
| Data Location | Binarly Cloud | Your Infrastructure |
| Custom Rules | Cloud Registry | Requires Harbor |
## Related Documentation
* [On-Prem v3 Installation](/on-prem/v3/installation)
* [On-Prem v3 Configuration](/on-prem/v3/configuration)
* [SaaS vs On-Prem Overview](/user-guides/about/deployment-architectures/SaaS-vs-onprem)
# SaaS API Considerations
Source: https://docs.binarly.io/api-reference/deployment/saas-considerations
API specifics for SaaS deployments
The Binarly Transparency Platform SaaS offering is fully managed by Binarly, requiring no infrastructure setup on your end.
## Base URLs
Each SaaS tenant has unique URLs based on your organization's slug:
| Service | URL Pattern |
| -------------- | ----------------------------------------------- |
| API Server | `https://dashboard-{slug}.binarly.cloud/api/v4` |
| Authentication | `https://auth-{slug}.binarly.cloud` |
| Dashboard | `https://dashboard-{slug}.binarly.cloud` |
> **Note**: Replace `{slug}` with your organization's tenant identifier (e.g., `https://dashboard-acme.binarly.cloud`). Contact your account representative if unsure of your slug.
## Authentication
SaaS deployments use Keycloak-based authentication:
* **M2M (CI/CD)**: Contact [support@binarly.io](mailto:support@binarly.io) to request API credentials. See [Setup API Client](/api-reference/authentication/create-api-client) for details.
* **User Access**: [User Authentication](/api-reference/authentication/generate-token)
## Key Benefits
* **Zero Infrastructure**: No servers, databases, or storage to manage.
* **Automatic Updates**: Platform updates are deployed automatically.
* **Isolated Tenants**: Each customer has a dedicated, isolated environment.
* **High Availability**: SLA-backed uptime guarantees.
## Connectivity Requirements
Your CI/CD systems or scripts need outbound HTTPS (port 443) access to:
* `*.binarly.cloud`
No inbound connections are required.
## Compliance
Binarly maintains **SOC 2 Type 2** compliance. Access compliance documents and reports at [trust.binarly.io](https://trust.binarly.io/).
## Data Residency
For information about data residency options and compliance requirements, contact [support@binarly.io](mailto:support@binarly.io).
# Upload Debug Symbols
Source: https://docs.binarly.io/api-reference/file/create-file-attachment
Upload debug symbol files (.pdb) to enhance the accuracy of security analysis. Debug symbols provide additional context that helps identify more vulnerabilities.
## When to Use This Endpoint
Upload debug symbols after uploading your binary image when:
* You have .pdb files available from your build process
* You want more accurate vulnerability detection
* You need better source code correlation in findings
> **Tip:** Debug symbols significantly improve analysis accuracy. Always upload them when available.
## Request
**Endpoint**
```
POST /api/v4/products/{product_id}/images/{image_id}/files
```
**Path Parameters**
| Parameter | Description |
| ------------ | ---------------------------------------------------------- |
| `product_id` | The product ID (e.g., `prod_abc123`) |
| `image_id` | The image ID from the upload response (e.g., `img_abc123`) |
**Headers**
| Header | Value |
| --------------- | ----------------------- |
| `Authorization` | `Bearer ` |
| `Content-Type` | `multipart/form-data` |
**Form Fields**
| Field | Required | Description |
| ------ | -------- | ---------------------------- |
| `file` | ✅ | The debug symbol file (.pdb) |
## Example Request - Single File
```bash theme={null}
# Set your variables
BINARLY_PRODUCT_ID="prod_abc123"
IMAGE_ID="img_abc123"
PDB_FILE="/path/to/firmware.pdb"
# Upload the debug symbol file
curl -X POST \
-H "Authorization: Bearer ${TOKEN}" \
-F "file=@${PDB_FILE}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}/files"
```
## Example Request - Batch Upload
If you have multiple .pdb files, upload them in a loop:
```bash theme={null}
# Set your variables
BINARLY_PRODUCT_ID="prod_abc123"
IMAGE_ID="img_abc123"
SYMBOLS_DIR="/path/to/symbols"
# Find and upload all .pdb files
find "$SYMBOLS_DIR" -name "*.pdb" | while read PDB_FILE; do
echo "Uploading: $PDB_FILE"
RESPONSE=$(curl -s -X POST \
-H "Authorization: Bearer ${TOKEN}" \
-F "file=@${PDB_FILE}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}/files")
# Check if upload succeeded
if echo "$RESPONSE" | jq -e '.id' > /dev/null 2>&1; then
echo "✅ Uploaded successfully"
else
echo "❌ Upload failed: $RESPONSE"
fi
done
```
## Response
Returns the created file object with upload confirmation.
```json theme={null}
{
"id": "01ABC123DEF456...",
"filename": "firmware.pdb",
"createTime": "2026-01-28T12:00:00Z"
}
```
| Field | Description |
| ------------ | ------------------------------------ |
| `id` | Unique file identifier (ULID format) |
| `filename` | The uploaded file name |
| `createTime` | Timestamp when file was uploaded |
## Best Practices
| Practice | Description |
| ------------------------- | --------------------------------------------------------------------- |
| **Upload after firmware** | Always upload debug symbols after the firmware image |
| **Include all symbols** | Upload all available .pdb files from your build |
| **Automate in CI/CD** | Integrate symbol upload into your build pipeline |
| **Keep symbols secure** | Debug symbols contain sensitive information - transfer via HTTPS only |
## Related
**User Guides**
* [Debugging Symbols Guide](/resource-center/debugging-symbols) - UI walkthrough for uploading and verifying PDB files
# Compare Findings
Source: https://docs.binarly.io/api-reference/finding/compare-findings
Search, filter, and compare security findings using the advanced Grid API.
## When to Use This Endpoint
Use this endpoint when you need to:
* **Compare Images**: Identify regressions between two binary file versions.
* **Advanced Filtering**: Filter findings by complex criteria not available in the simple list.
* **Export**: Retrieve large datasets of findings.
## Request
**Endpoint**
```
POST /api/v4/grids/findings:gridList
```
**Headers**
| Header | Value |
| --------------- | ----------------------- |
| `Authorization` | `Bearer ` |
| `Content-Type` | `application/json` |
**Body**
| Field | Required | Description |
| --------- | -------- | ------------------------------------- |
| `filters` | ✅ | Array of filter objects (see example) |
## Filter Reference
> \[!IMPORTANT] The grid API requires at least one scope filter (`productId` or `imageId`) to return results. Requests without a scope filter may return 400 Bad Request.
Supported filter fields:
| Field | Values | Description |
| --------------------- | ---------------------------------------------------------------- | ----------------------------------------------- |
| `productId` | `` | **Required scope filter** - Product ID to query |
| `imageId` | `` | Alternative scope filter - Specific image ID |
| `issueStatus` | `new`, `inProgress`, `remediated`, `rejected` | Workflow status of the finding |
| `severity` | `critical`, `high`, `medium`, `low`, `informational` | Finding severity level |
| `findingType` | `knownVulnerability`, `maliciousCode`, `dependencyVulnerability` | Type of finding |
| `compareLeftImageId` | `` | **Baseline** image ID for comparison |
| `compareRightImageId` | `` | **Target** image ID for comparison |
## Example Request - Compare Images
To identify what changed between a baseline and a target image:
```bash theme={null}
BASELINE_ID="01JQ..."
TARGET_ID="01JY..."
curl -s -X POST \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"filters": [
{"field": "compareLeftImageId", "value": "'"${BASELINE_ID}"'", "comparator": "equals"},
{"field": "compareRightImageId", "value": "'"${TARGET_ID}"'", "comparator": "equals"},
{"field": "issueStatus", "value": ["new", "inProgress"], "comparator": "in"}
]
}' \
"${BINARLY_API_URL}/api/v4/grids/findings:gridList"
```
> \[!TIP] The `issueStatus` filter requires the `in` comparator with an array of status values, not `equals` with a single string.
## Response
Returns a paginated list of findings with comparison status.
```json theme={null}
{
"total": 5,
"rows": [
{
"id": "finding_123",
"pname": "OpenSSL Vulnerability",
"severity": "high",
"comparison": {
"status": "new"
}
}
]
}
```
| Field | Description |
| ------- | ----------------------------------------- |
| `total` | Total count of findings matching criteria |
| `rows` | Array of finding objects |
# Get Image
Source: https://docs.binarly.io/api-reference/image/get-image
Retrieve details about a specific binary images, including hash checksums and metadata.
## When to Use This Endpoint
Use this endpoint to:
* Verify an image upload was successful.
* Retrieve SHA256/MD5 hashes for integrity verification.
* Check the basic metadata of a firmare image.
## Request
**Endpoint**
```
GET /api/v4/products/{productId}/images/{imageId}
```
**Path Parameters**
| Parameter | Required | Description |
| ----------- | -------- | ----------- |
| `productId` | ✅ | Product ID |
| `imageId` | ✅ | Image ID |
**Headers**
| Header | Value |
| --------------- | ----------------------- |
| `Authorization` | `Bearer ` |
## Example Request
```bash theme={null}
BINARLY_PRODUCT_ID="01JQPGDX8QW0YJ0XEKV1EVG534"
IMAGE_ID="01JYJ0W0AACGC7QT1Q21SRWG94"
curl -s \
-H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}"
```
## Response
```json theme={null}
{
"id": "01JYJ0W0AACGC7QT1Q21SRWG94",
"name": "Firmware v1.2",
"version": "1.2.0",
"createTime": "2024-01-20T10:00:00Z",
"author": "user@example.com",
"parent": "products/01JQPGDX8QW0YJ0XEKV1EVG534"
}
```
| Field | Description |
| ------------ | --------------------------------------- |
| `id` | Unique image identifier |
| `name` | Human-readable name |
| `version` | Firmware version string |
| `createTime` | When the image was uploaded |
| `author` | User or service that uploaded the image |
| `parent` | Parent product resource path |
> \[!NOTE] To retrieve file checksums (SHA256, MD5), see the [SBOM Report](/api-reference/report/sbom-report) endpoint which includes hash information in the component inventory.
# List Images
Source: https://docs.binarly.io/api-reference/image/list-images
List all binary images associated with a product.
## When to Use This Endpoint
Use this endpoint to iterate through your firmware inventory or find a specific image ID based on version or name.
## Request
**Endpoint**
```
GET /api/v4/products/{productId}/images
```
**Path Parameters**
| Parameter | Required | Description |
| ----------- | -------- | ----------------------------- |
| `productId` | ✅ | Product ID to list images for |
**Headers**
| Header | Value |
| --------------- | ----------------------- |
| `Authorization` | `Bearer ` |
## Example Request
```bash theme={null}
BINARLY_PRODUCT_ID="01JQPGDX8QW0YJ0XEKV1EVG534"
curl -s \
-H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images"
```
## Response
```json theme={null}
{
"images": [
{
"id": "01JYJ0W0AACGC7QT1Q21SRWG94",
"name": "Firmware v1.2",
"version": "1.2.0"
}
]
}
```
| Field | Description |
| -------- | ---------------------- |
| `images` | Array of image objects |
# Upload Image
Source: https://docs.binarly.io/api-reference/image/upload-image
Upload a binary image to the Binarly Transparency Platform for security analysis. The upload process uses a secure, three-step workflow involving a pre-signed URL.
Obtain a secure, time-limited pre-signed URL for uploading your firmware binary.
Upload your file directly to the provided pre-signed URL.
Notify the platform that the upload is complete to trigger the security analysis.
## Step 1: Generate Upload URL
Call this endpoint to receive a temporary upload URL and a unique file ID.
```bash Request theme={null}
# Replace ${BINARLY_PRODUCT_ID} with your product ID
curl -H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/tempFiles:generateUploadUrl"
```
### Response
The response contains the `uploadUrl` for the next step and an `id` to identify the file.
```json theme={null}
{
"id": "01ABC123DEF456...",
"uploadUrl": "https://storage.googleapis.com/..."
}
```
## Step 2: Upload a Binary
Upload your binary file to the `uploadUrl` obtained in Step 1. Use a **PUT** request with the binary content.
```bash Request theme={null}
# Upload the file binary to the pre-signed URL
curl -X PUT --data-binary @"path/to/firmware.bin" "${UPLOAD_URL}"
```
>
> This request does not require the `Authorization` header, as the URL itself is signed.
>
## Step 3: Finalize Upload
Once the binary upload is successful (HTTP 200), call this endpoint to finalize the process and start the scan.
### request
The `id` received from Step 1.
A human-readable name for the binary image.
The binary file version string (e.g., "1.0.0").
The binary file. Required by the API even when using `tempFileId` (content is taken from pre-signed upload).
```bash Request theme={null}
# Finalize the upload using tempFileId from Step 1
curl -X POST \
-H "Authorization: Bearer ${TOKEN}" \
-F "tempFileId=${TEMP_FILE_ID}" \
-F "imageName=My Firmware Image" \
-F "version=1.0.0" \
-F "file=@./firmware.bin" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images:upload"
```
### Response
Returns the created image object, confirming the scan has started.
```json theme={null}
{
"id": "img_abc123",
"name": "My Firmware Image",
"version": "1.0.0",
"createTime": "2026-01-28T12:00:00Z",
"scans": [
{
"id": "scan_xyz789",
"latestScanState": {
"type": "new"
}
}
]
}
```
# Get Started
Source: https://docs.binarly.io/api-reference/introduction
Welcome to the Binarly Transparency Platform API
The Binarly Transparency Platform API allows you to automate firmware security analysis, integrate vulnerability scanning into your CI/CD pipelines, and retrieve detailed security insights programmatically.
## Choose Your Path
Select the authentication method that matches your use case to get started quickly.
![Authentication Overview]()
I need to integrate Binarly into a build pipeline (Jenkins, GitLab, GitHub Actions).
**Go here to set up machine-to-machine authentication.**
I need to run ad-hoc queries, test endpoints, or build a custom script.
**Go here to generate a personal access token.**
## Interactive Documentation
Explore our full API reference and test endpoints directly in the browser using our Swagger UI.
**Swagger UI URL**:
`https:///api/v4/swagger/`
> **Note**: Replace `` in the URL above with your specific dashboard domain (e.g., `dashboard-myorg.binarly.cloud`) to access the interactive documentation for your instance.
## New to Binarly?
If you're just getting started, check out the [First Scan Guide](/user-guides/get-started/first-scan) for a walkthrough of the dashboard interface.
# Create Product
Source: https://docs.binarly.io/api-reference/product/create-product
Create a new product container to organize your scanned binary images.
## When to Use This Endpoint
Use this endpoint to programmatically provision new products, for example when onboarding a new device model in your CI/CD pipeline.
* **Organization**: Group related images.
* **Automation**: setup environments dynamically.
## Request
**Endpoint**
```
POST /api/v4/products
```
**Headers**
| Header | Value |
| --------------- | ----------------------- |
| `Authorization` | `Bearer ` |
| `Content-Type` | `application/json` |
**Body**
| Field | Required | Description |
| ------ | -------- | ---------------------------------- |
| `name` | ✅ | The simplified name of the product |
## Example Request
```bash theme={null}
curl -s -X POST \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{"name": "New Product Series"}' \
"${BINARLY_API_URL}/api/v4/products"
```
## Response
```json theme={null}
{
"id": "products/01JQPGDX8QW0YJ0XEKV1EVG534",
"name": "New Product Series",
"createTime": "2024-01-28T12:00:00Z"
}
```
| Field | Description |
| ------------ | ----------------------------------------------------- |
| `id` | Unique identifier (resource name) for the new product |
| `name` | The name provided in the request |
| `createTime` | Creation timestamp |
# Get Product
Source: https://docs.binarly.io/api-reference/product/get-product
Retrieve detailed information about a specific product. Use this endpoint to verify product details or retrieve metadata like creation time.
## When to Use This Endpoint
Use this endpoint when you have a `productId` and need to:
* Verify the product exists.
* Retrieve the product's full name or metadata.
* Debug permissions or access.
## Request
**Endpoint**
```
GET /api/v4/products/{productId}
```
**Path Parameters**
| Parameter | Required | Description |
| ----------- | -------- | ------------------------------------------- |
| `productId` | ✅ | The unique identifier of the product (ULID) |
**Headers**
| Header | Value |
| --------------- | ----------------------- |
| `Authorization` | `Bearer ` |
## Example Request
```bash theme={null}
BINARLY_PRODUCT_ID="01JQPGDX8QW0YJ0XEKV1EVG534"
curl -s \
-H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}"
```
## Response
```json theme={null}
{
"id": "products/01JQPGDX8QW0YJ0XEKV1EVG534",
"name": "My Firmware Product",
"description": "Production firmware for device X",
"createTime": "2024-01-20T10:00:00Z",
"author": "user@example.com"
}
```
| Field | Description |
| ------------- | ---------------------------------------- |
| `id` | Full product resource name |
| `name` | The display name of the product |
| `description` | Optional product description |
| `createTime` | Timestamp when the product was created |
| `author` | User or service that created the product |
# List Products
Source: https://docs.binarly.io/api-reference/product/list-products
Retrieve the list of products available to your account. Use this endpoint to find the `PRODUCT_ID` needed for uploading binary images.
## When to Use This Endpoint
Before uploading an image to scan, you need to know which product to associate it with. This endpoint returns all products you have access to, allowing you to:
* Find the correct product ID for your image
* Verify you have access to the intended product
* Discover available products in your organization
## Request
**Endpoint**
```
GET /api/v4/products
```
**Headers**
| Header | Value |
| --------------- | ----------------------- |
| `Authorization` | `Bearer ` |
## Example Request
```bash theme={null}
curl -H "Authorization: Bearer ${TOKEN}" \
${BINARLY_API_URL}/api/v4/products
```
## Response
```json theme={null}
{
"products": [
{
"id": "products/prod_abc123",
"name": "My Firmware Product",
"description": "Production firmware for device X",
"createTime": "2025-06-15T10:00:00Z",
"author": "user@example.com"
},
{
"id": "products/prod_def456",
"name": "Development Firmware",
"description": "Development builds for testing",
"createTime": "2025-07-20T14:30:00Z",
"author": "user@example.com"
}
]
}
```
| Field | Description |
| ------------- | ------------------------------------------------ |
| `id` | Full product path (e.g., `products/prod_abc123`) |
| `name` | Human-readable product name |
| `description` | Product description |
| `createTime` | When the product was created (ISO 8601 format) |
| `author` | User or service that created the product |
## Extracting the Product ID
The `id` field contains the full path (e.g., `products/prod_abc123`). When uploading images, use only the ID portion:
| Full Path | Product ID to Use |
| ---------------------- | ----------------- |
| `products/prod_abc123` | `prod_abc123` |
| `products/prod_def456` | `prod_def456` |
### Alternative: Get Product ID from Dashboard URL
For testing or quick access, you can find the Product ID directly in the Binarly Dashboard URL.
1. Open the product page in the dashboard.
2. Look at the browser URL: `https://dashboard-.binarly.cloud/products/01KFNEGZEAWM1F3JBYKXDXGPDM/images/...`
3. The string after `/products/` is your Product ID (e.g., `01KFNEGZEAWM1F3JBYKXDXGPDM`).
## Example: Find Product and Upload
```bash theme={null}
# Step 1: List products and find the ID
PRODUCTS=$(curl -s -H "Authorization: Bearer ${TOKEN}" \
${BINARLY_API_URL}/api/v4/products)
# Step 2: Extract the first product ID (example using jq)
BINARLY_PRODUCT_ID=$(echo $PRODUCTS | jq -r '.products[0].id' | sed 's/products\///')
echo "Using product ID: $BINARLY_PRODUCT_ID"
# Step 3: Use this product ID for uploading (see upload-image endpoint)
```
# CBOM Reports
Source: https://docs.binarly.io/api-reference/report/cbom-report
Download the Cryptographic Bill of Materials (CBOM), listing all cryptographic assets found in the binary file.
## When to Use This Endpoint
Use this endpoint to:
* Inventory cryptographic algorithms and keys.
* Identify weak or non-compliant cryptography (e.g., Post-Quantum Readiness).
## Request
**Endpoint**
```
GET /api/v4/products/{productId}/images/{imageId}/cbomReport:{format}
```
**Path Parameters**
| Parameter | Required | Description |
| ----------- | -------- | -------------------------- |
| `productId` | ✅ | Product ID |
| `imageId` | ✅ | Image ID |
| `format` | ✅ | Report format: `cycloneDX` |
**Headers**
| Header | Value |
| --------------- | ----------------------- |
| `Authorization` | `Bearer ` |
## Example Request
```bash theme={null}
curl -s \
-H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}/cbomReport:cycloneDX" \
-o cbom.json
```
## Response
Returns the CBOM JSON document.
# Findings Report
Source: https://docs.binarly.io/api-reference/report/findings-report
Download a comprehensive security findings report in PDF, JSON, or CSV format.
## When to Use This Endpoint
Use this endpoint to:
* Generate human-readable PDF reports for stakeholders.
* Export raw finding data (JSON/CSV) for custom analytics.
## Request
### PDF Format (GET)
```
GET /api/v4/products/{productId}/images/{imageId}
```
**Query Parameters**
| Parameter | Required | Description |
| ------------- | -------- | --------------------------------------------------------- |
| `contentType` | ❌ | `pdf` |
| `imageFields` | ❌ | `findings` (include to get full report with all findings) |
### JSON Format (GET)
```
GET /api/v4/products/{productId}/images/{imageId}
```
**Query Parameters**
| Parameter | Required | Description |
| ------------- | -------- | ----------- |
| `imageFields` | ❌ | `findings` |
***
**Path Parameters** (all formats)
| Parameter | Required | Description |
| ----------- | -------- | ----------- |
| `productId` | ✅ | Product ID |
| `imageId` | ✅ | Image ID |
**Headers**
| Header | Value |
| --------------- | ----------------------- |
| `Authorization` | `Bearer ` |
## Example Requests
```bash theme={null}
# PDF report (full)
curl -s \
-H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}?contentType=pdf&imageFields=findings" \
-o report.pdf
# JSON report (POST)
curl -s \
-H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}?imageFields=findings"
```
## Response
Returns the requested file content (binary PDF or text/json).
# PQC Compliance Report
Source: https://docs.binarly.io/api-reference/report/pqc-report
Download the Post-Quantum Cryptography (PQC) compliance report to assess your binary file's cryptographic readiness for quantum computing threats.
## When to Use This Endpoint
Use this endpoint to:
* Identify cryptographic implementations vulnerable to quantum attacks
* Generate compliance documentation for PQC readiness audits
* Track cryptographic migration progress across releases
## Request
**Endpoint**
```
GET /api/v4/products/{productId}/images/{imageId}/cryptographicMaterialsReport?mode=pqc-compliance
```
**Path Parameters**
| Parameter | Required | Description |
| ----------- | -------- | ----------- |
| `productId` | ✅ | Product ID |
| `imageId` | ✅ | Image ID |
**Query Parameters**
| Parameter | Required | Description |
| ------------- | -------- | -------------------------------- |
| `mode` | ✅ | Must be `pqc-compliance` |
| `contentType` | ✅ | Response format: `json` or `pdf` |
**Headers**
| Header | Value |
| --------------- | ----------------------- |
| `Authorization` | `Bearer ` |
## Example Requests
```bash theme={null}
# JSON format
curl -s \
-H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}/cryptographicMaterialsReport?mode=pqc-compliance&contentType=json" \
-o pqc-compliance.json
# PDF format
curl -s \
-H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}/cryptographicMaterialsReport?mode=pqc-compliance&contentType=pdf" \
-o pqc-compliance.pdf
```
## Response
Returns the PQC compliance report in the requested format (JSON or PDF).
The JSON report includes:
* Cryptographic algorithms detected
* Quantum vulnerability assessment
* Recommended migration paths
## Related
* [CBOM Report](/api-reference/report/cbom-report) - Full cryptographic bill of materials
* [Compliance Artifacts](/api-reference/use-cases/compliance-artifacts) - All compliance reports
# SBOM Reports
Source: https://docs.binarly.io/api-reference/report/sbom-report
Download the Software Bill of Materials (SBOM) for a specific binary image in industry-standard formats.
## When to Use This Endpoint
Use this endpoint to:
* Generate compliance artifacts for releases.
* Import your firmware inventory into other security tools.
## Request
**Endpoint**
```
GET /api/v4/products/{productId}/images/{imageId}/sbomReport:{format}?contentType=json
```
**Path Parameters**
| Parameter | Required | Description |
| ----------- | -------- | ------------------------------------ |
| `productId` | ✅ | Product ID |
| `imageId` | ✅ | Image ID |
| `format` | ✅ | Report format: `cycloneDX` or `SPDX` |
**Query Parameters**
| Parameter | Required | Description |
| ------------- | -------- | ----------------------------- |
| `contentType` | ✅ | Response content type: `json` |
**Headers**
| Header | Value |
| --------------- | ----------------------- |
| `Authorization` | `Bearer ` |
## Example Request
```bash theme={null}
curl -s \
-H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}/sbomReport:cycloneDX?contentType=json" \
-o sbom.json
```
## Response
Returns the SBOM JSON document.
# VEX Reports
Source: https://docs.binarly.io/api-reference/report/vex-report
Download the Vulnerability Exploitability eXchange (VEX) report, which details the exploitability status of vulnerabilities found in your binaries.
## When to Use This Endpoint
Use this endpoint to:
* Communicate which vulnerabilities are "fixed" or "not affected".
* Provide machine-readable security advisories to customers.
## Request
**Endpoint**
```
GET /api/v4/products/{productId}/images/{imageId}/vexReport:{format}
```
**Path Parameters**
| Parameter | Required | Description |
| ----------- | -------- | --------------------------------------- |
| `productId` | ✅ | Product ID |
| `imageId` | ✅ | Image ID |
| `format` | ✅ | Report format: `openVEX` or `cycloneDX` |
**Headers**
| Header | Value |
| --------------- | ----------------------- |
| `Authorization` | `Bearer ` |
## Example Request
```bash theme={null}
curl -s \
-H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}/vexReport:openVEX" \
-o vex.json
```
## Response
Returns the VEX JSON document.
# Get Scan
Source: https://docs.binarly.io/api-reference/scan/get-scan
Retrieve details about a specific security scan, including the status and high-level statistics.
## When to Use This Endpoint
Use this endpoint to:
* Poll the status of a running scan.
* Retrieve summary statistics like finding counts and risk scores.
## Request
**Endpoint**
```
GET /api/v4/products/{productId}/images/{imageId}/scans/{scanId}
```
**Path Parameters**
| Parameter | Required | Description |
| ----------- | -------- | ----------- |
| `productId` | ✅ | Product ID |
| `imageId` | ✅ | Image ID |
| `scanId` | ✅ | Scan ID |
**Headers**
| Header | Value |
| --------------- | ----------------------- |
| `Authorization` | `Bearer ` |
## Example Request
```bash theme={null}
BINARLY_PRODUCT_ID="01JQPGDX8QW0YJ0XEKV1EVG534"
IMAGE_ID="01JYJ0W0AACGC7QT1Q21SRWG94"
SCAN_ID="01JZ30CYZY52F5BPR3AAJ2DP89"
curl -s \
-H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}/scans/${SCAN_ID}"
```
## Response
```json theme={null}
{
"id": "01JZ30CYZY52F5BPR3AAJ2DP89",
"parent": "products/01JQPGDX8QW0YJ0XEKV1EVG534/images/01JYJ0W0AACGC7QT1Q21SRWG94",
"createTime": "2024-01-20T10:00:00Z",
"author": "user@example.com",
"latestScanState": {
"type": "completed",
"updateTime": "2024-01-20T10:30:00Z"
}
}
```
| Field | Description |
| ---------------------------- | --------------------------------------------------------- |
| `id` | Scan ID |
| `parent` | Parent resource path (product/image) |
| `createTime` | When the scan was created |
| `author` | User or service that initiated the scan |
| `latestScanState` | Object containing scan status |
| `latestScanState.type` | Status: `in_progress`, `completed`, `failed`, `cancelled` |
| `latestScanState.updateTime` | When the status was last updated |
# List Scans
Source: https://docs.binarly.io/api-reference/scan/list-scans
Monitor the progress of security scans after uploading a binary image. Use this endpoint to check when analysis is complete.
## When to Use This Endpoint
After uploading a binary image, use this endpoint to:
* Check if the security scan is still in progress
* Determine when analysis has completed
* Get the scan ID for retrieving detailed results
## Request
**Endpoint - List All Scans for an Image**
```
GET /api/v4/products/{product_id}/images/{image_id}/scans?status=true
```
**Endpoint - Get a Specific Scan**
```
GET /api/v4/products/{product_id}/images/{image_id}/scans/{scan_id}?status=true
```
**Path Parameters**
| Parameter | Description |
| ------------ | ---------------------------------------------------------- |
| `product_id` | The product ID (e.g., `prod_abc123`) |
| `image_id` | The image ID returned from the upload (e.g., `img_abc123`) |
| `scan_id` | (Optional) Specific scan ID to query |
**Query Parameters**
| Parameter | Required | Description |
| --------- | -------- | ------------------------------------------------ |
| `status` | ✅ | Set to `true` to include scan status information |
**Headers**
| Header | Value |
| --------------- | ----------------------- |
| `Authorization` | `Bearer ` |
## Example Request
```bash theme={null}
# Set your variables (from the upload response)
BINARLY_PRODUCT_ID="prod_abc123"
IMAGE_ID="img_abc123"
# Check scan status
curl -H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}/scans?status=true"
```
## Response
```json theme={null}
{
"scans": [
{
"id": "scan_xyz789",
"createTime": "2026-01-26T15:30:01Z",
"latestScanState": {
"type": "in_progress"
}
}
]
}
```
## Scan States
The status is found in the `latestScanState.type` field:
| State | Description | Action |
| -------------------- | ------------------------------ | ----------------------------- |
| `in_progress` | Analysis is currently running | Wait and poll again |
| `completed` | Analysis finished successfully | Results are ready to view |
| `no_scans` | No scans exist for the image | Check if upload succeeded |
| `status_unavailable` | Status could not be determined | Contact support if persistent |
## Polling for Completion
To wait for a scan to complete, poll the endpoint periodically:
```bash theme={null}
# Poll every 30 seconds until scan completes
while true; do
STATUS=$(curl -s -H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}/scans?status=true" \
| jq -r '.scans[0].latestScanState.type')
echo "Current status: $STATUS"
if [ "$STATUS" = "completed" ]; then
echo "✅ Scan completed!"
break
elif [ "$STATUS" = "in_progress" ]; then
echo "⏳ Still scanning... waiting 30 seconds"
sleep 30
else
echo "❌ Unexpected status: $STATUS"
break
fi
done
```
## Scan Duration
Scan duration depends on the binary image size, complexity and content:
| Image Size | Typical Duration |
| ---------- | ---------------- |
| \< 64 MB | 5-10 minutes |
| 64-500 MB | 10-60 minutes |
| > 500 MB | 1+ hours |
> **Tip:** For large images, consider setting up webhook notifications instead of polling.
# List Components
Source: https://docs.binarly.io/api-reference/scan/scan-components
List all software components (SBOM inventory) identified during the scan.
## When to Use This Endpoint
Use this endpoint to:
* Retrieve a raw list of detected components for inventory management.
* Verify if a specific library version exists in your binary file.
## Request
**Endpoint**
```
GET /api/v4/products/{productId}/images/{imageId}/scans/{scanId}/components
```
**Path Parameters**
| Parameter | Required | Description |
| ----------- | -------- | ----------- |
| `productId` | ✅ | Product ID |
| `imageId` | ✅ | Image ID |
| `scanId` | ✅ | Scan ID |
**Headers**
| Header | Value |
| --------------- | ----------------------- |
| `Authorization` | `Bearer ` |
## Example Request
```bash theme={null}
curl -s \
-H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}/scans/${SCAN_ID}/components"
```
## Response
```json theme={null}
{
"components": [
{
"name": "OpenSSL",
"version": "1.1.1g",
"cpe": "cpe:2.3:a:openssl:openssl:1.1.1g:*:*:*:*:*:*:*"
}
]
}
```
| Field | Description |
| --------- | --------------------------------------------- |
| `name` | Component name |
| `version` | Detected version (optional) |
| `cpe` | Common Platform Enumeration string (optional) |
# Troubleshooting
Source: https://docs.binarly.io/api-reference/troubleshooting
Get help with the Binarly Transparency Platform
When contacting support, you can provide your deployment's release information to help diagnose issues faster.
## Download Release Information
Click on the **version number** (e.g., v3.6) in the bottom-left corner of the dashboard to download your `release-info.yaml` file.
![Click version number to download release-info.yaml]()
Send this file to [support@binarly.io](mailto:support@binarly.io) or share it via Slack when reporting issues.
## Example Release Information
The downloaded file contains your deployment's version and configuration details:
```yaml theme={null}
chart:
version: 1.x.x
dependencies:
- name: server
version: 4.x.x
- name: dashboard
version: 3.x.x
global:
version: 3.6
images:
dashboard:
image:
tag: ""
server:
image:
tag: ""
normalise:
image:
tag: 2.x.x
# ... additional scan tools
scanToolsConfiguration:
cryptoscan:
enabled: true
cvehunt:
enabled: true
fwhunt:
enabled: true
# ... additional tool configurations
features:
copilot: true
reports:
cbom: true
pqcCompliance: true
vex: true
# ... additional features
```
## Contact Support
* **Email**: [support@binarly.io](mailto:support@binarly.io)
* **Slack**: Your organization's Binarly support channel
* **Include**: Organization name, deployment type (SaaS/On-Prem), and `release-info.yaml`
# Bash Script
Source: https://docs.binarly.io/api-reference/use-cases/cicd/bash
Universal bash script for CI/CD integration
This bash script demonstrates the complete workflow using `curl` and `jq`. It works with any CI/CD system that supports shell scripts.
## Prerequisites
* `curl` and `jq` installed
* Environment variables configured
## Complete Script
```bash theme={null}
#!/bin/bash
set -e
# Configuration (Set these as environment variables in your CI)
# BINARLY_CLIENT_ID="your-client-id"
# BINARLY_CLIENT_SECRET="your-client-secret"
# BINARLY_AUTH_URL="https://auth-{slug}.binarly.cloud/realms/BinarlyRealm/protocol/openid-connect/token"
# BINARLY_API_URL="https://dashboard-{slug}.binarly.cloud"
# BINARLY_FIRMWARE_FILE="./firmware.bin"
# BINARLY_PRODUCT_ID="prod_123456"
# 1. Authenticate (M2M)
echo "LOG: Authenticating..."
TOKEN_RES=$(curl -s --fail-with-body \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_id=${BINARLY_CLIENT_ID}" \
--data-urlencode "client_secret=${BINARLY_CLIENT_SECRET}" \
"${BINARLY_AUTH_URL}")
TOKEN=$(echo $TOKEN_RES | jq -r '.access_token')
# 2. Upload Firmware (3-Step Flow)
echo "LOG: Generating Upload URL..."
UPLOAD_RES=$(curl -s -H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/tempFiles:generateUploadUrl")
UPLOAD_URL=$(echo $UPLOAD_RES | jq -r '.uploadUrl')
TEMP_ID=$(echo $UPLOAD_RES | jq -r '.id')
echo "LOG: Uploading Binary..."
curl -s -X PUT --data-binary @${BINARLY_FIRMWARE_FILE} "${UPLOAD_URL}"
echo "LOG: Finalizing Upload..."
# Generate unique image name with timestamp to avoid conflicts
IMAGE_NAME="CI Build ${BUILD_NUMBER:-0}-$(date +%Y%m%d%H%M%S)"
IMAGE_RES=$(curl -s -H "Authorization: Bearer ${TOKEN}" \
-F "tempFileId=${TEMP_ID}" \
-F "imageName=${IMAGE_NAME}" \
-F "version=1.0.${BUILD_NUMBER:-0}" \
-F "file=@${BINARLY_FIRMWARE_FILE}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images:upload")
IMAGE_ID=$(echo $IMAGE_RES | jq -r '.id')
if [ "$IMAGE_ID" == "null" ] || [ -z "$IMAGE_ID" ]; then
echo "ERROR: Upload failed. Response: $IMAGE_RES"
exit 1
fi
echo "LOG: Scan started for Image ID: ${IMAGE_ID}"
# 3. Poll for Results
echo "LOG: Waiting for scan to complete..."
while true; do
sleep 30
SCAN_RES=$(curl -s -H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}/scans?status=true")
STATUS=$(echo $SCAN_RES | jq -r '.scans[0].latestScanState.type')
echo "LOG: Scan status: ${STATUS}"
# Check if scan is complete
if [ "$STATUS" == "completed" ]; then
echo "SUCCESS: Security analysis completed."
break
elif [ "$STATUS" == "failed" ]; then
echo "ERROR: Scan failed"
exit 1
elif [ "$STATUS" != "running" ] && [ "$STATUS" != "queued" ] && [ "$STATUS" != "pending" ]; then
echo "ERROR: Unexpected scan status: ${STATUS}"
exit 1
fi
# Continue waiting for running/queued/pending states
done
```
## Environment Variables
| Variable | Description |
| ----------------------- | -------------------------- |
| `BINARLY_CLIENT_ID` | Keycloak API Client ID |
| `BINARLY_CLIENT_SECRET` | Keycloak API Client Secret |
| `BINARLY_AUTH_URL` | Authentication endpoint |
| `BINARLY_API_URL` | API base URL |
| `BINARLY_PRODUCT_ID` | Target product ID |
| `BINARLY_FIRMWARE_FILE` | Path to firmware binary |
| `BUILD_NUMBER` | CI build number (optional) |
## Usage
```bash theme={null}
# Set environment variables
export BINARLY_CLIENT_ID="my-api-client"
export BINARLY_CLIENT_SECRET="secret123"
export BINARLY_AUTH_URL="https://auth-{slug}.binarly.cloud/realms/BinarlyRealm/protocol/openid-connect/token"
export BINARLY_API_URL="https://dashboard-{slug}.binarly.cloud"
export BINARLY_PRODUCT_ID="01JQPGDX8QW0YJ0XEKV1EVG534"
export BINARLY_FIRMWARE_FILE="./build/firmware.bin"
export BUILD_NUMBER="42"
# Run script
./binarly-scan.sh
```
## 4. Verify Results
After the scan completes, verify the results and optionally fail the build based on findings.
```bash theme={null}
#!/bin/bash
# Binarly CI/CD Verification Script
# Requires: TOKEN, BINARLY_API_URL, BINARLY_PRODUCT_ID, IMAGE_ID from upload
# Optional: FAIL_ON_STATUS (default: "new,inProgress")
set -e
# Configuration: Which statuses should fail the build
FAIL_ON_STATUS="${FAIL_ON_STATUS:-new,inProgress}"
echo "Binarly Security Verification"
echo "Failing on statuses: ${FAIL_ON_STATUS}"
echo ""
# 1. Get all images for the product
IMAGES_RES=$(curl -s -H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images")
IMAGE_COUNT=$(echo "$IMAGES_RES" | jq '.images | length')
echo "Product has ${IMAGE_COUNT} image(s)"
# Initialize statistics
RESOLVED=0
UNCHANGED=0
NEW_ISSUES=0
# 2. If multiple images exist, compare latest with previous
if [ "$IMAGE_COUNT" -gt 1 ]; then
# Sort images by createTime descending and get IDs of two most recent
LATEST_ID=$(echo "$IMAGES_RES" | jq -r '[.images | sort_by(.createTime) | reverse][0][0].id')
PREVIOUS_ID=$(echo "$IMAGES_RES" | jq -r '[.images | sort_by(.createTime) | reverse][0][1].id')
echo "Comparing images:"
echo " Previous: ${PREVIOUS_ID}"
echo " Latest: ${LATEST_ID}"
echo ""
# Count RESOLVED findings (only in previous image = left side)
RESOLVED=$(curl -s -X POST \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"filters": [
{"field": "compareLeftImageId", "value": "'"${PREVIOUS_ID}"'", "comparator": "equals"},
{"field": "compareRightImageId", "value": "'"${LATEST_ID}"'", "comparator": "equals"},
{"field": "compareSide", "value": "left", "comparator": "equals"}
]
}' \
"${BINARLY_API_URL}/api/v4/grids/findings:gridList" | jq '.total // 0')
# Count UNCHANGED findings (present in both images)
UNCHANGED=$(curl -s -X POST \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"filters": [
{"field": "compareLeftImageId", "value": "'"${PREVIOUS_ID}"'", "comparator": "equals"},
{"field": "compareRightImageId", "value": "'"${LATEST_ID}"'", "comparator": "equals"},
{"field": "compareSide", "value": "both", "comparator": "equals"}
]
}' \
"${BINARLY_API_URL}/api/v4/grids/findings:gridList" | jq '.total // 0')
# Count NEW findings (only in latest image = right side)
NEW_ISSUES=$(curl -s -X POST \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"filters": [
{"field": "compareLeftImageId", "value": "'"${PREVIOUS_ID}"'", "comparator": "equals"},
{"field": "compareRightImageId", "value": "'"${LATEST_ID}"'", "comparator": "equals"},
{"field": "compareSide", "value": "right", "comparator": "equals"}
]
}' \
"${BINARLY_API_URL}/api/v4/grids/findings:gridList" | jq '.total // 0')
echo "Comparison Statistics:"
printf " Resolved from previous: %6d\n" "$RESOLVED"
printf " Unchanged (still present): %6d\n" "$UNCHANGED"
printf " Newly introduced: %6d\n" "$NEW_ISSUES"
echo ""
fi
# 3. Check for findings matching configured statuses (using 'in' comparator with array)
# Convert comma-separated statuses to JSON array
STATUSES_JSON=$(echo "$FAIL_ON_STATUS" | tr ',' '\n' | jq -R . | jq -s .)
# Use LATEST_ID if available (from comparison), otherwise use IMAGE_ID from upload step
CHECK_IMAGE_ID="${LATEST_ID:-${IMAGE_ID}}"
TOTAL_ACTIONABLE=$(curl -s -X POST \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"filters": [
{"field": "imageId", "value": "'"${CHECK_IMAGE_ID}"'", "comparator": "equals"},
{"field": "issueStatus", "value": '"${STATUSES_JSON}"', "comparator": "in"}
]
}' \
"${BINARLY_API_URL}/api/v4/grids/findings:gridList" | jq '.total // 0')
echo " Statuses checked: ${FAIL_ON_STATUS}"
echo ""
echo "Total actionable findings: ${TOTAL_ACTIONABLE}"
echo ""
# 4. Pass/Fail decision
if [ "$TOTAL_ACTIONABLE" -gt 0 ]; then
echo "BUILD FAILED: ${TOTAL_ACTIONABLE} actionable finding(s)"
exit 1
else
echo "BUILD PASSED: No actionable findings"
exit 0
fi
```
For detailed explanation of the verification logic, see [Verify Results](/api-reference/use-cases/cicd/verify-results).
# GitHub Actions
Source: https://docs.binarly.io/api-reference/use-cases/cicd/github-actions
GitHub Actions workflow for firmware scanning
Integrate Binarly security scanning into your GitHub Actions workflow.
## Workflow File
Create `.github/workflows/binarly-scan.yml`:
```yaml theme={null}
name: Binarly Firmware Scan
on:
push:
paths:
- 'firmware/**'
workflow_dispatch:
env:
# Replace {slug} with your organization's tenant identifier
BINARLY_AUTH_URL: https://auth-{slug}.binarly.cloud/realms/BinarlyRealm/protocol/openid-connect/token
BINARLY_API_URL: https://dashboard-{slug}.binarly.cloud
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Build Firmware
run: make firmware # Your build command
- name: Authenticate with Binarly
id: auth
run: |
TOKEN=$(curl -s --fail-with-body \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_id=${{ secrets.BINARLY_CLIENT_ID }}" \
--data-urlencode "client_secret=${{ secrets.BINARLY_CLIENT_SECRET }}" \
"$BINARLY_AUTH_URL" | jq -r '.access_token')
echo "token=$TOKEN" >> $GITHUB_OUTPUT
- name: Upload Firmware
id: upload
run: |
# Generate pre-signed URL
UPLOAD_RES=$(curl -s -H "Authorization: Bearer ${{ steps.auth.outputs.token }}" \
"$BINARLY_API_URL/api/v4/products/${{ secrets.BINARLY_PRODUCT_ID }}/tempFiles:generateUploadUrl")
UPLOAD_URL=$(echo $UPLOAD_RES | jq -r '.uploadUrl')
TEMP_ID=$(echo $UPLOAD_RES | jq -r '.id')
# Upload binary
curl -s -X PUT --data-binary @./build/firmware.bin "$UPLOAD_URL"
# Finalize
IMAGE_RES=$(curl -s -H "Authorization: Bearer ${{ steps.auth.outputs.token }}" \
-F "tempFileId=$TEMP_ID" \
-F "imageName=GitHub Build ${{ github.run_number }}" \
-F "version=${{ github.sha }}" \
-F "file=@./build/firmware.bin" \
"$BINARLY_API_URL/api/v4/products/${{ secrets.BINARLY_PRODUCT_ID }}/images:upload")
IMAGE_ID=$(echo $IMAGE_RES | jq -r '.id')
echo "image_id=$IMAGE_ID" >> $GITHUB_OUTPUT
- name: Wait for Scan
run: |
STATUS="running"
while [ "$STATUS" != "completed" ]; do
sleep 30
SCAN_RES=$(curl -s -H "Authorization: Bearer ${{ steps.auth.outputs.token }}" \
"$BINARLY_API_URL/api/v4/products/${{ secrets.BINARLY_PRODUCT_ID }}/images/${{ steps.upload.outputs.image_id }}/scans?status=true")
STATUS=$(echo $SCAN_RES | jq -r '.scans[0].latestScanState.type')
echo "Scan status: $STATUS"
[ "$STATUS" == "failed" ] && exit 1
done
echo "Scan completed successfully"
- name: Verify Results
id: verify
env:
FAIL_ON_STATUS: "new,inProgress" # Configurable: new,inProgress,rejected,remediated
run: |
echo "Binarly Security Verification"
echo "Failing on statuses: $FAIL_ON_STATUS"
TOKEN="${{ steps.auth.outputs.token }}"
BINARLY_PRODUCT_ID="${{ secrets.BINARLY_PRODUCT_ID }}"
IMAGE_ID="${{ steps.upload.outputs.image_id }}"
# Get all images for the product
IMAGES_RES=$(curl -s -H "Authorization: Bearer $TOKEN" \
"$BINARLY_API_URL/api/v4/products/$BINARLY_PRODUCT_ID/images")
IMAGE_COUNT=$(echo "$IMAGES_RES" | jq '.images | length')
echo "Product has ${IMAGE_COUNT} image(s)"
# If multiple images exist, compare latest with previous
if [ "$IMAGE_COUNT" -gt 1 ]; then
# Sort images by createTime descending
LATEST_ID=$(echo "$IMAGES_RES" | jq -r '[.images | sort_by(.createTime) | reverse][0][0].id')
PREVIOUS_ID=$(echo "$IMAGES_RES" | jq -r '[.images | sort_by(.createTime) | reverse][0][1].id')
echo "Comparing: $PREVIOUS_ID → $LATEST_ID"
# Count RESOLVED findings
RESOLVED=$(curl -s -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"filters":[
{"field":"compareLeftImageId","value":"'"$PREVIOUS_ID"'","comparator":"equals"},
{"field":"compareRightImageId","value":"'"$LATEST_ID"'","comparator":"equals"},
{"field":"compareSide","value":"left","comparator":"equals"}
]}' \
"$BINARLY_API_URL/api/v4/grids/findings:gridList" | jq '.total // 0')
# Count UNCHANGED findings
UNCHANGED=$(curl -s -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"filters":[
{"field":"compareLeftImageId","value":"'"$PREVIOUS_ID"'","comparator":"equals"},
{"field":"compareRightImageId","value":"'"$LATEST_ID"'","comparator":"equals"},
{"field":"compareSide","value":"both","comparator":"equals"}
]}' \
"$BINARLY_API_URL/api/v4/grids/findings:gridList" | jq '.total // 0')
# Count NEW findings
NEW_ISSUES=$(curl -s -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"filters":[
{"field":"compareLeftImageId","value":"'"$PREVIOUS_ID"'","comparator":"equals"},
{"field":"compareRightImageId","value":"'"$LATEST_ID"'","comparator":"equals"},
{"field":"compareSide","value":"right","comparator":"equals"}
]}' \
"$BINARLY_API_URL/api/v4/grids/findings:gridList" | jq '.total // 0')
echo "Resolved: $RESOLVED | Unchanged: $UNCHANGED | New: $NEW_ISSUES"
fi
# Check for findings matching configured statuses (using 'in' comparator with array)
STATUSES_JSON=$(echo "$FAIL_ON_STATUS" | tr ',' '\n' | jq -R . | jq -s .)
# Use LATEST_ID if available (from comparison), otherwise use IMAGE_ID from upload step
CHECK_IMAGE_ID="${LATEST_ID:-$IMAGE_ID}"
TOTAL_ACTIONABLE=$(curl -s -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"filters":[
{"field":"imageId","value":"'"$CHECK_IMAGE_ID"'","comparator":"equals"},
{"field":"issueStatus","value":'"$STATUSES_JSON"',"comparator":"in"}
]}' \
"$BINARLY_API_URL/api/v4/grids/findings:gridList" | jq '.total // 0')
echo " Statuses checked: $FAIL_ON_STATUS"
echo "Total actionable findings: $TOTAL_ACTIONABLE"
if [ "$TOTAL_ACTIONABLE" -gt 0 ]; then
echo "BUILD FAILED: $TOTAL_ACTIONABLE actionable finding(s)"
exit 1
fi
echo "BUILD PASSED: No actionable findings"
```
## Required Secrets
Configure these in **Settings → Secrets and variables → Actions**:
| Secret | Description |
| ----------------------- | -------------------------- |
| `BINARLY_CLIENT_ID` | Keycloak API Client ID |
| `BINARLY_CLIENT_SECRET` | Keycloak API Client Secret |
| `BINARLY_PRODUCT_ID` | Target product ID |
## Triggering the Workflow
The workflow runs automatically when:
* Files in `firmware/` are pushed
* Manually triggered via `workflow_dispatch`
Modify the `on:` section to match your project structure.
For detailed explanation of the verification logic, see [Verify Results](/api-reference/use-cases/cicd/verify-results).
# GitLab CI
Source: https://docs.binarly.io/api-reference/use-cases/cicd/gitlab-ci
GitLab CI/CD configuration for firmware scanning
Integrate Binarly security scanning into your GitLab CI/CD pipeline.
## Configuration File
Create `.gitlab-ci.yml`:
```yaml theme={null}
stages:
- build
- scan
variables:
# Replace {slug} with your organization's tenant identifier
BINARLY_AUTH_URL: https://auth-{slug}.binarly.cloud/realms/BinarlyRealm/protocol/openid-connect/token
BINARLY_API_URL: https://dashboard-{slug}.binarly.cloud
build:
stage: build
script:
- make firmware
artifacts:
paths:
- build/firmware.bin
binarly-scan:
stage: scan
image: curlimages/curl:latest
needs:
- build
before_script:
- apk add --no-cache jq
script:
# Authenticate
- |
TOKEN=$(curl -s --fail-with-body \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_id=${BINARLY_CLIENT_ID}" \
--data-urlencode "client_secret=${BINARLY_CLIENT_SECRET}" \
"$BINARLY_AUTH_URL" | jq -r '.access_token')
# Generate upload URL
- |
UPLOAD_RES=$(curl -s -H "Authorization: Bearer $TOKEN" \
"$BINARLY_API_URL/api/v4/products/${BINARLY_PRODUCT_ID}/tempFiles:generateUploadUrl")
UPLOAD_URL=$(echo $UPLOAD_RES | jq -r '.uploadUrl')
TEMP_ID=$(echo $UPLOAD_RES | jq -r '.id')
# Upload binary
- curl -s -X PUT --data-binary @./build/firmware.bin "$UPLOAD_URL"
# Finalize upload
- |
IMAGE_RES=$(curl -s -H "Authorization: Bearer $TOKEN" \
-F "tempFileId=$TEMP_ID" \
-F "imageName=GitLab Pipeline $CI_PIPELINE_ID" \
-F "version=$CI_COMMIT_SHORT_SHA" \
-F "file=@./build/firmware.bin" \
"$BINARLY_API_URL/api/v4/products/${BINARLY_PRODUCT_ID}/images:upload")
IMAGE_ID=$(echo $IMAGE_RES | jq -r '.id')
echo "Image ID: $IMAGE_ID"
# Poll for completion
- |
STATUS="running"
while [ "$STATUS" != "completed" ]; do
sleep 30
SCAN_RES=$(curl -s -H "Authorization: Bearer $TOKEN" \
"$BINARLY_API_URL/api/v4/products/${BINARLY_PRODUCT_ID}/images/$IMAGE_ID/scans?status=true")
STATUS=$(echo $SCAN_RES | jq -r '.scans[0].latestScanState.type')
echo "Scan status: $STATUS"
[ "$STATUS" == "failed" ] && exit 1
done
echo "Scan completed successfully"
# Verify Results
- |
echo "Binarly Security Verification"
# Configuration
FAIL_ON_STATUS="${FAIL_ON_STATUS:-new,inProgress}"
echo "Failing on statuses: $FAIL_ON_STATUS"
# Get all images
IMAGES_RES=$(curl -s -H "Authorization: Bearer $TOKEN" \
"$BINARLY_API_URL/api/v4/products/${BINARLY_PRODUCT_ID}/images")
IMAGE_COUNT=$(echo "$IMAGES_RES" | jq '.images | length')
echo "Product has ${IMAGE_COUNT} image(s)"
# Compare if multiple images exist
if [ "$IMAGE_COUNT" -gt 1 ]; then
# Sort images by createTime descending
LATEST_ID=$(echo "$IMAGES_RES" | jq -r '[.images | sort_by(.createTime) | reverse][0][0].id')
PREVIOUS_ID=$(echo "$IMAGES_RES" | jq -r '[.images | sort_by(.createTime) | reverse][0][1].id')
echo "Comparing: $PREVIOUS_ID → $LATEST_ID"
RESOLVED=$(curl -s -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"filters":[{"field":"compareLeftImageId","value":"'"$PREVIOUS_ID"'","comparator":"equals"},{"field":"compareRightImageId","value":"'"$LATEST_ID"'","comparator":"equals"},{"field":"compareSide","value":"left","comparator":"equals"}]}' \
"$BINARLY_API_URL/api/v4/grids/findings:gridList" | jq '.total // 0')
UNCHANGED=$(curl -s -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"filters":[{"field":"compareLeftImageId","value":"'"$PREVIOUS_ID"'","comparator":"equals"},{"field":"compareRightImageId","value":"'"$LATEST_ID"'","comparator":"equals"},{"field":"compareSide","value":"both","comparator":"equals"}]}' \
"$BINARLY_API_URL/api/v4/grids/findings:gridList" | jq '.total // 0')
NEW_ISSUES=$(curl -s -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"filters":[{"field":"compareLeftImageId","value":"'"$PREVIOUS_ID"'","comparator":"equals"},{"field":"compareRightImageId","value":"'"$LATEST_ID"'","comparator":"equals"},{"field":"compareSide","value":"right","comparator":"equals"}]}' \
"$BINARLY_API_URL/api/v4/grids/findings:gridList" | jq '.total // 0')
echo "Resolved: $RESOLVED | Unchanged: $UNCHANGED | New: $NEW_ISSUES"
fi
# Check for findings matching configured statuses (using 'in' comparator with array)
STATUSES_JSON=$(echo "$FAIL_ON_STATUS" | tr ',' '\n' | jq -R . | jq -s .)
# Use LATEST_ID if available (from comparison), otherwise use IMAGE_ID from upload step
CHECK_IMAGE_ID="${LATEST_ID:-$IMAGE_ID}"
TOTAL_ACTIONABLE=$(curl -s -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"filters":[{"field":"imageId","value":"'"$CHECK_IMAGE_ID"'","comparator":"equals"},{"field":"issueStatus","value":'"$STATUSES_JSON"',"comparator":"in"}]}' \
"$BINARLY_API_URL/api/v4/grids/findings:gridList" | jq '.total // 0')
echo " Statuses checked: $FAIL_ON_STATUS"
echo "Total actionable findings: $TOTAL_ACTIONABLE"
if [ "$TOTAL_ACTIONABLE" -gt 0 ]; then
echo "BUILD FAILED: $TOTAL_ACTIONABLE actionable finding(s)"
exit 1
fi
echo "BUILD PASSED: No actionable findings"
```
## Required Variables
Configure in **Settings → CI/CD → Variables**:
| Variable | Flags | Description |
| ----------------------- | ----------------- | -------------------------- |
| `BINARLY_CLIENT_ID` | Protected, Masked | Keycloak API Client ID |
| `BINARLY_CLIENT_SECRET` | Protected, Masked | Keycloak API Client Secret |
| `BINARLY_PRODUCT_ID` | Protected | Target product ID |
## GitLab-Specific Variables
The script uses these built-in GitLab variables:
* `$CI_PIPELINE_ID` – Unique pipeline identifier
* `$CI_COMMIT_SHORT_SHA` – Short commit hash for version tracking
For detailed explanation of the verification logic, see [Verify Results](/api-reference/use-cases/cicd/verify-results).
# Jenkins Pipeline
Source: https://docs.binarly.io/api-reference/use-cases/cicd/jenkins
Jenkinsfile pipeline for firmware scanning
Integrate Binarly security scanning into your Jenkins pipeline.
## Jenkinsfile
```groovy theme={null}
pipeline {
agent any
environment {
// Replace {slug} with your organization's tenant identifier
BINARLY_AUTH_URL = 'https://auth-{slug}.binarly.cloud/realms/BinarlyRealm/protocol/openid-connect/token'
BINARLY_API_URL = 'https://dashboard-{slug}.binarly.cloud'
BINARLY_CLIENT_ID = credentials('binarly-client-id')
BINARLY_CLIENT_SECRET = credentials('binarly-client-secret')
BINARLY_PRODUCT_ID = credentials('binarly-product-id')
}
stages {
stage('Build Firmware') {
steps {
sh 'make firmware'
}
}
stage('Authenticate') {
steps {
script {
def tokenResponse = sh(
script: """
curl -s --fail-with-body \\
-H "Content-Type: application/x-www-form-urlencoded" \\
--data-urlencode "grant_type=client_credentials" \\
--data-urlencode "client_id=${BINARLY_CLIENT_ID}" \\
--data-urlencode "client_secret=${BINARLY_CLIENT_SECRET}" \\
"${BINARLY_AUTH_URL}"
""",
returnStdout: true
)
env.BINARLY_TOKEN = readJSON(text: tokenResponse).access_token
}
}
}
stage('Upload Firmware') {
steps {
script {
// Generate upload URL
def uploadRes = sh(
script: """
curl -s -H "Authorization: Bearer ${BINARLY_TOKEN}" \\
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/tempFiles:generateUploadUrl"
""",
returnStdout: true
)
def uploadData = readJSON(text: uploadRes)
// Upload binary
sh "curl -s -X PUT --data-binary @./build/firmware.bin '${uploadData.uploadUrl}'"
// Finalize
def imageRes = sh(
script: """
curl -s -H "Authorization: Bearer ${BINARLY_TOKEN}" \\
-F "tempFileId=${uploadData.id}" \\
-F "imageName=Jenkins Build ${BUILD_NUMBER}" \\
-F "version=${BUILD_NUMBER}" \\
-F "file=@./build/firmware.bin" \\
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images:upload"
""",
returnStdout: true
)
env.IMAGE_ID = readJSON(text: imageRes).id
echo "Image uploaded: ${env.IMAGE_ID}"
}
}
}
stage('Wait for Scan') {
steps {
script {
def status = 'running'
while (status != 'completed') {
sleep 30
def scanRes = sh(
script: """
curl -s -H "Authorization: Bearer ${BINARLY_TOKEN}" \\
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}/scans?status=true"
""",
returnStdout: true
)
status = readJSON(text: scanRes).scans[0].latestScanState.type
echo "Scan status: ${status}"
if (status == 'failed') {
error 'Binarly scan failed'
}
}
echo 'Scan completed successfully'
}
}
}
stage('Verify Results') {
steps {
script {
echo 'Binarly Security Verification'
def failOnStatus = env.FAIL_ON_STATUS ?: 'new,inProgress'
echo "Failing on statuses: ${failOnStatus}"
// Get all images
def imagesRes = sh(
script: """
curl -s -H "Authorization: Bearer ${BINARLY_TOKEN}" \\
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images"
""",
returnStdout: true
)
def imagesData = readJSON(text: imagesRes)
def imageCount = imagesData.images.size()
echo "Product has ${imageCount} image(s)"
// Compare if multiple images exist
if (imageCount > 1) {
// Sort images by createTime descending
def sortedImages = imagesData.images.sort { a, b -> b.createTime <=> a.createTime }
def latestId = sortedImages[0].id
def previousId = sortedImages[1].id
echo "Comparing: ${previousId} → ${latestId}"
def resolved = sh(
script: """
curl -s -X POST -H "Authorization: Bearer ${BINARLY_TOKEN}" \\
-H "Content-Type: application/json" \\
-d '{"filters":[{"field":"compareLeftImageId","value":"${previousId}","comparator":"equals"},{"field":"compareRightImageId","value":"${latestId}","comparator":"equals"},{"field":"compareSide","value":"left","comparator":"equals"}]}' \\
"${BINARLY_API_URL}/api/v4/grids/findings:gridList" | jq '.total // 0'
""",
returnStdout: true
).trim()
def unchanged = sh(
script: """
curl -s -X POST -H "Authorization: Bearer ${BINARLY_TOKEN}" \\
-H "Content-Type: application/json" \\
-d '{"filters":[{"field":"compareLeftImageId","value":"${previousId}","comparator":"equals"},{"field":"compareRightImageId","value":"${latestId}","comparator":"equals"},{"field":"compareSide","value":"both","comparator":"equals"}]}' \\
"${BINARLY_API_URL}/api/v4/grids/findings:gridList" | jq '.total // 0'
""",
returnStdout: true
).trim()
def newIssues = sh(
script: """
curl -s -X POST -H "Authorization: Bearer ${BINARLY_TOKEN}" \\
-H "Content-Type: application/json" \\
-d '{"filters":[{"field":"compareLeftImageId","value":"${previousId}","comparator":"equals"},{"field":"compareRightImageId","value":"${latestId}","comparator":"equals"},{"field":"compareSide","value":"right","comparator":"equals"}]}' \\
"${BINARLY_API_URL}/api/v4/grids/findings:gridList" | jq '.total // 0'
""",
returnStdout: true
).trim()
echo "Resolved: ${resolved} | Unchanged: ${unchanged} | New: ${newIssues}"
}
// Check for findings matching configured statuses (using 'in' comparator with array)
def statusesArray = failOnStatus.split(',').collect { '"' + it.trim() + '"' }.join(',')
// Use latestId if available (from comparison), otherwise use IMAGE_ID from upload step
def checkImageId = latestId ?: env.IMAGE_ID
def totalActionable = sh(
script: """
curl -s -X POST -H "Authorization: Bearer ${BINARLY_TOKEN}" \\
-H "Content-Type: application/json" \\
-d '{"filters":[{"field":"imageId","value":"${checkImageId}","comparator":"equals"},{"field":"issueStatus","value":[${statusesArray}],"comparator":"in"}]}' \\
"${BINARLY_API_URL}/api/v4/grids/findings:gridList" | jq '.total // 0'
""",
returnStdout: true
).trim().toInteger()
echo " Statuses checked: ${failOnStatus}"
echo "Total actionable findings: ${totalActionable}"
if (totalActionable > 0) {
error "BUILD FAILED: ${totalActionable} actionable finding(s)"
}
echo 'BUILD PASSED: No actionable findings'
}
}
}
}
}
```
## Required Credentials
Configure in **Manage Jenkins → Credentials**:
| Credential ID | Type | Description |
| ----------------------- | ----------- | -------------------------- |
| `binarly-client-id` | Secret text | Keycloak API Client ID |
| `binarly-client-secret` | Secret text | Keycloak API Client Secret |
| `binarly-product-id` | Secret text | Target product ID |
## Pipeline Configuration
1. Create a new Pipeline job
2. Configure Pipeline script from SCM or paste the Jenkinsfile
3. Ensure credentials are created in Jenkins
For detailed explanation of the verification logic, see [Verify Results](/api-reference/use-cases/cicd/verify-results).
# Overview
Source: https://docs.binarly.io/api-reference/use-cases/cicd/overview
Learn how to automate firmware security scanning in your CI/CD pipeline.
This guide demonstrates how to integrate the Binarly Transparency Platform into your CI/CD pipeline.
## Prerequisites
Before integrating, ensure you have:
* **API Client credentials** (`BINARLY_CLIENT_ID` and `BINARLY_CLIENT_SECRET`) – See [Setup API Client](/api-reference/authentication/create-api-client)
* *SaaS customers*: Contact [support@binarly.io](mailto:support@binarly.io) to request credentials
* *On-Prem customers*: Create credentials via Keycloak Admin Console
* **Product ID** (`BINARLY_PRODUCT_ID`) for your firmware project
* **Binary file** to scan
## Workflow Overview
All CI/CD integrations follow the same four-step workflow:
```mermaid theme={null}
graph LR
A[Authenticate] --> B[Upload]
B --> C[Poll]
C --> D[Verify]
```
1. **Authenticate**: Obtain an access token using Client Credentials
2. **Upload**: Submit the binary image for analysis
3. **Poll**: Check the scan status until completion
4. **Verify**: Pass/fail the build based on findings – [See Details](/api-reference/use-cases/cicd/verify-results)
## Choose Your Platform
Universal script using curl and jq
Native GitHub workflow integration
Jenkinsfile pipeline example
.gitlab-ci.yml configuration
Pass/fail builds with comparison statistics
## Next Steps
* **Set up your Client**: See [Setup API Client](/api-reference/authentication/create-api-client)
# Verify Results
Source: https://docs.binarly.io/api-reference/use-cases/cicd/verify-results
Pass/fail CI/CD builds based on findings analysis with comparison statistics
After a scan completes, verify the results to make pass/fail decisions for your CI/CD pipeline. This page explains the verification logic and provides implementation examples.
## Verification Logic
The verification workflow handles two scenarios:
```mermaid theme={null}
flowchart TD
A[Scan Complete] --> B{Multiple Images?}
B -->|No| C[Check for Actionable Findings]
B -->|Yes| D[Compare with Previous Image]
D --> E[Display Statistics]
E --> C
C -->|Found| F[FAIL Build]
C -->|None| G[PASS Build]
```
### Scenario 1: Single Image (First Scan)
When the product contains only one image (the latest scan), the verification checks for findings matching the configured statuses. If found, the build fails.
### Scenario 2: Multiple Images (Comparison)
When multiple images exist, the verification:
1. Compares the **latest image** with the **previous image**
2. Reports statistics on resolved, unchanged, and newly introduced findings
3. Fails if any findings with configured statuses exist in the latest image
## Configuration
### Finding Status Filter
Control which finding statuses cause the build to fail using the `FAIL_ON_STATUS` environment variable:
| Status | Description |
| ------------ | ------------------------------------- |
| `new` | Newly discovered, not yet triaged |
| `inProgress` | Currently being investigated |
| `rejected` | Marked as false positive or won't fix |
| `remediated` | Fixed but still detected (unusual) |
**Default:** `new,inProgress` – Fails on findings that require attention.
**Examples:**
```bash theme={null}
# Fail only on new (untriaged) findings
export FAIL_ON_STATUS="new"
# Fail on new and in-progress (default)
export FAIL_ON_STATUS="new,inProgress"
# Strict: Fail on any non-remediated finding
export FAIL_ON_STATUS="new,inProgress,rejected"
```
## Comparison Statistics
The comparison API categorizes findings into three groups:
| Status | Meaning | API Filter |
| ------------- | ------------------------------------ | ------------------------------ |
| **Resolved** | Was in previous image, not in latest | `comparison.status=notFound` |
| **Unchanged** | Present in both images | `comparison.status=notChanged` |
| **New** | Not in previous, appeared in latest | `comparison.status=found` |
## API Endpoints Used
| Endpoint | Purpose |
| ----------------------------------------- | ----------------------------------------------------- |
| `GET /api/v4/products/{productId}/images` | List images to determine count and get IDs |
| `POST /api/v4/grids/findings:gridList` | Query findings with filters for status and comparison |
## Implementation
```bash theme={null}
#!/bin/bash
# Binarly CI/CD Verification Script
# Requires: curl, jq
# Environment: TOKEN, BINARLY_API_URL, BINARLY_PRODUCT_ID, IMAGE_ID (from upload step)
# Optional: FAIL_ON_STATUS (default: "new,inProgress")
set -e
# Configuration: Which statuses should fail the build
FAIL_ON_STATUS="${FAIL_ON_STATUS:-new,inProgress}"
echo "Binarly Security Verification"
echo "Failing on statuses: ${FAIL_ON_STATUS}"
echo ""
# 1. Get all images for the product
IMAGES_RES=$(curl -s -H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images")
IMAGE_COUNT=$(echo "$IMAGES_RES" | jq '.images | length')
echo "Product has ${IMAGE_COUNT} image(s)"
# Initialize statistics
RESOLVED=0
UNCHANGED=0
NEW_ISSUES=0
# 2. If multiple images exist, compare latest with previous
if [ "$IMAGE_COUNT" -gt 1 ]; then
# Sort images by createTime descending and get IDs of two most recent
LATEST_ID=$(echo "$IMAGES_RES" | jq -r '[.images | sort_by(.createTime) | reverse][0][0].id')
PREVIOUS_ID=$(echo "$IMAGES_RES" | jq -r '[.images | sort_by(.createTime) | reverse][0][1].id')
echo "Comparing images:"
echo " Previous: ${PREVIOUS_ID}"
echo " Latest: ${LATEST_ID}"
echo ""
# Count RESOLVED findings (only in previous image = left side)
RESOLVED=$(curl -s -X POST \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"filters": [
{"field": "compareLeftImageId", "value": "'"${PREVIOUS_ID}"'", "comparator": "equals"},
{"field": "compareRightImageId", "value": "'"${LATEST_ID}"'", "comparator": "equals"},
{"field": "compareSide", "value": "left", "comparator": "equals"}
]
}' \
"${BINARLY_API_URL}/api/v4/grids/findings:gridList" | jq '.total // 0')
# Count UNCHANGED findings (present in both images)
UNCHANGED=$(curl -s -X POST \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"filters": [
{"field": "compareLeftImageId", "value": "'"${PREVIOUS_ID}"'", "comparator": "equals"},
{"field": "compareRightImageId", "value": "'"${LATEST_ID}"'", "comparator": "equals"},
{"field": "compareSide", "value": "both", "comparator": "equals"}
]
}' \
"${BINARLY_API_URL}/api/v4/grids/findings:gridList" | jq '.total // 0')
# Count NEW findings (only in latest image = right side)
NEW_ISSUES=$(curl -s -X POST \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"filters": [
{"field": "compareLeftImageId", "value": "'"${PREVIOUS_ID}"'", "comparator": "equals"},
{"field": "compareRightImageId", "value": "'"${LATEST_ID}"'", "comparator": "equals"},
{"field": "compareSide", "value": "right", "comparator": "equals"}
]
}' \
"${BINARLY_API_URL}/api/v4/grids/findings:gridList" | jq '.total // 0')
echo "Comparison Statistics:"
printf " Resolved from previous: %6d\n" "$RESOLVED"
printf " Unchanged (still present): %6d\n" "$UNCHANGED"
printf " Newly introduced: %6d\n" "$NEW_ISSUES"
echo ""
fi
# 3. Check for findings matching configured statuses (using 'in' comparator with array)
# Convert comma-separated statuses to JSON array
STATUSES_JSON=$(echo "$FAIL_ON_STATUS" | tr ',' '\n' | jq -R . | jq -s .)
# Use LATEST_ID if available (from comparison), otherwise use IMAGE_ID from upload step
CHECK_IMAGE_ID="${LATEST_ID:-${IMAGE_ID}}"
TOTAL_ACTIONABLE=$(curl -s -X POST \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"filters": [
{"field": "imageId", "value": "'"${CHECK_IMAGE_ID}"'", "comparator": "equals"},
{"field": "issueStatus", "value": '"${STATUSES_JSON}"', "comparator": "in"}
]
}' \
"${BINARLY_API_URL}/api/v4/grids/findings:gridList" | jq '.total // 0')
echo " Statuses checked: ${FAIL_ON_STATUS}"
echo ""
echo "Total actionable findings: ${TOTAL_ACTIONABLE}"
echo ""
# 4. Pass/Fail decision
if [ "$TOTAL_ACTIONABLE" -gt 0 ]; then
echo "BUILD FAILED: ${TOTAL_ACTIONABLE} actionable finding(s)"
exit 1
else
echo "BUILD PASSED: No actionable findings"
exit 0
fi
```
## Output Example
**Multi-image scenario with issues:**
```text theme={null}
Binarly Security Verification
Failing on statuses: new,inProgress
Product has 5 image(s)
Comparing images:
Previous: 01JYJ0W0AACGC7QT1Q21SRWG94
Latest: 01JYJX8K2BBDF9PT3R22TSWH05
Comparison Statistics:
Resolved from previous: 12
Unchanged (still present): 45
Newly introduced: 3
new: 2
inProgress: 1
Total actionable findings: 3
BUILD FAILED: 3 actionable finding(s)
```
## Next Steps
* **Triage Findings**: Use the [Binarly Dashboard](https://dashboard.binarly.cloud) to review and triage findings
* **Adjust Thresholds**: Combine with severity filters - see [Compare Findings API](/api-reference/finding/compare-findings)
* **See Also**: [Compare Findings API](/api-reference/finding/compare-findings) for advanced filtering options
# Compliance Artifacts
Source: https://docs.binarly.io/api-reference/use-cases/compliance-artifacts
Generate SBOMs, VEX, CBOM, and PQC compliance reports for supply chain security.
Software supply chain security requires transparent, machine-readable compliance artifacts. The Binarly API enables you to programmatically generate industry-standard reports for auditing, vulnerability disclosure, and post-quantum cryptography readiness assessment.
## Available Reports
| Report | Purpose | Documentation |
| ------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------- |
| **SBOM** | Software Bill of Materials - inventory of all software components | [SBOM Report](/api-reference/report/sbom-report) |
| **VEX** | Vulnerability Exploitability - communicate which vulnerabilities are actionable | [VEX Report](/api-reference/report/vex-report) |
| **CBOM** | Cryptographic Bill of Materials - inventory of crypto assets | [CBOM Report](/api-reference/report/cbom-report) |
| **PQC** | Post-Quantum Cryptography Compliance - readiness for quantum threats | [PQC Report](/api-reference/report/pqc-report) |
| **Findings** | Security Findings - comprehensive security analysis results | [Findings Report](/api-reference/report/findings-report) |
## Use Case: Regulatory Compliance
When preparing for regulatory submissions (e.g., FDA, EU Cyber Resilience Act), you typically need:
1. **SBOM** - Required by most regulations to demonstrate software transparency
2. **VEX** - Demonstrates how you're addressing known vulnerabilities
3. **PQC Report** - Shows cryptographic posture for quantum readiness
## Use Case: Continuous Compliance in CI/CD
Integrate compliance artifact generation into your release pipeline:
1. Upload binary image → [Upload Image](/api-reference/image/upload-image)
2. Wait for scan completion → [List Scans](/api-reference/scan/list-scans)
3. Download artifacts → Individual report endpoints above
## Use Case: Third-Party Audits
For supply chain audits:
1. Generate **SBOM** for software inventory
2. Generate **CBOM** for cryptographic material inventory
3. Generate **Findings Report** for security posture overview
## Automation Script
Download all compliance artifacts for a binary image:
```bash theme={null}
#!/bin/bash
set -e
# Configuration (set these environment variables)
# BINARLY_API_URL, BINARLY_PRODUCT_ID, TOKEN
IMAGE_ID="${1:?Usage: $0 }"
OUTPUT_DIR="./compliance-artifacts"
mkdir -p "$OUTPUT_DIR"
echo "Downloading compliance artifacts for image: $IMAGE_ID"
# See individual report endpoints for full options:
# - /api-reference/report/sbom-report
# - /api-reference/report/vex-report
# - /api-reference/report/cbom-report
# - /api-reference/report/pqc-report
# - /api-reference/report/findings-report
BASE="${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}"
curl -s -H "Authorization: Bearer ${TOKEN}" "${BASE}/sbomReport:cycloneDX?contentType=json" -o "${OUTPUT_DIR}/sbom.json"
curl -s -H "Authorization: Bearer ${TOKEN}" "${BASE}/vexReport:openVEX" -o "${OUTPUT_DIR}/vex.json"
curl -s -H "Authorization: Bearer ${TOKEN}" "${BASE}/cbomReport:cycloneDX" -o "${OUTPUT_DIR}/cbom.json"
curl -s -H "Authorization: Bearer ${TOKEN}" "${BASE}/cryptographicMaterialsReport?mode=pqc-compliance&contentType=json" -o "${OUTPUT_DIR}/pqc.json"
curl -s -H "Authorization: Bearer ${TOKEN}" "${BASE}?contentType=pdf&imageFields=findings" -o "${OUTPUT_DIR}/findings.pdf"
echo "✓ Artifacts saved to: $OUTPUT_DIR"
```
## Related
**API Reference**
* [CI/CD Integration](/api-reference/use-cases/cicd/overview)
* [Triage & Analysis](/api-reference/use-cases/triage-and-analysis)
**User Guides**
* [SBOM Export Guide](/user-guides/export/sbom) - UI walkthrough and use cases
* [VEX Export Guide](/user-guides/export/vex) - Vulnerability disclosure workflows
* [CBOM Export Guide](/user-guides/export/cbom) - Cryptographic inventory
* [PQC Compliance Guide](/user-guides/export/pqc) - Detailed report contents and generation
# Triage & Analysis
Source: https://docs.binarly.io/api-reference/use-cases/triage-and-analysis
Identify regressions and analyze security findings.
Effective triage involves comparing scanned binary file versions to spot regressions and analyzing individual findings for root cause analysis.
## 1. Regressions (Compare Images)
To identify what changed between two versions (e.g., a "Golden Master" vs. a new Release Candidate), use the comparison feature.
### Workflow
1. Identify the **Baseline Image ID** (e.g., previous stable version).
2. Identify the **Target Image ID** (e.g., new build).
3. Use the `findings:gridList` endpoint to filter by comparison IDs.
```bash Compare theme={null}
# Compare Baseline (Left) vs Target (Right)
curl -s -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"filters": [
{"field": "compareLeftImageId", "value": "ID_BASELINE", "comparator": "equals"},
{"field": "compareRightImageId", "value": "ID_TARGET", "comparator": "equals"}
]
}' \
"${BINARLY_API_URL}/api/v4/grids/findings:gridList"
```
## 2. Analyze Findings
Once you identify a critical finding, retrieve its full details.
1. Get the `findingId` from the comparison results.
2. Call the Get Finding endpoint (see Finding Reference).
```bash theme={null}
curl -s \
-H "Authorization: Bearer $TOKEN" \
"${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/findings/$FINDING_ID"
```
## Related
**User Guides**
* [Compare Images](/user-guides/image-scans/compare) - UI walkthrough for comparing firmware versions
# Configuration
Source: https://docs.binarly.io/on-prem/v2/configuration
# Configure Binarly charts
There are two custom Helm charts for Binarly On-Prem:
1. Secrets: Creates necessary secrets for the Binarly components.
2. Binarly: Deploys core On-Prem components following the ArgoCD App of Apps pattern.
Let's describe how to configure them:
## Binarly Secrets
The chart is configured in `k8s/apps/binarly-secrets/values.yaml.gotmpl`. At least, it's necessary to provide the following secrets:
```yaml theme={null}
secrets:
# @schema
# type: string
# @schema
# -- API key for NVD. It will fill the value from $BINARLY_SECRET_NVD_API_KEY
nvdApiKey: {{ requiredEnv "BINARLY_SECRET_NVD_API_KEY" }}
# @schema
# type: string
# @schema
# -- Integration Secret for server component. It will fill the value from $BINARLY_SECRET_SERVER_INTEGRATION_SECRET
serverIntegrationSecret: {{ requiredEnv "BINARLY_SECRET_SERVER_INTEGRATION_SECRET" }}
```
Thanks to helmfile, we can easily provide those environment variables from our `.envrc.local` file:
```bash theme={null}
## Binarly Secrets
# NOTE: Fill these secrets with the provided credentials
export BINARLY_SECRET_NVD_API_KEY=""
export BINARLY_SECRET_SERVER_INTEGRATION_SECRET=""
```
Ensure to fill the values accordingly. For the `BINARLY_SECRET_NVD_API_KEY` it should be present on the Bitwarden secrets.
For the `BINARLY_SECRET_SERVER_INTEGRATION_SECRET` you need to generate it with the following terminal command:
```bash theme={null}
openssl rand -base64 32
```
Ensure you keep the previous secrets in a safe place. If you loose access to the `BINARLY_SECRET_SERVER_INTEGRATION_SECRET` the Jira integration will be lost as the data is encrypted into the database.
Remember if you make any change to the `.envrc.local` file to apply again the `source .envrc.local` command to refresh the latest environment variables!
Now, you can render the output of the Secrets chart to quickly check what secrets are going to be created in the Kubernetes cluster:
```bash theme={null}
helmfile template --selector name=secrets
```
The secrets will be installed in the following steps. You can also `lint` the Chart for any misconfiguration or issues as well:
```bash theme={null}
helmfile lint --selector name=secrets
```
## Binarly Chart
This is the main chart that contains the ArgoCD App of Apps for Binarly. Configuration is stored in `k8s/apps/binarly/values.yaml.gotmpl`.
### Image Pull Secrets
By default, the Binarly deployment will use the authenticated registry provided by Customer Success and this is already set up. If you are using a custom registry, this can be adjusted in the `binarly-repository-secrets` file.
`imagePullSecrets` should match with the `binarly-registry` (that is being created on the `secrets` chart). This will allow to access the custom Artifact Registry to be able to pull docker images:
```yaml theme={null}
global:
imagePullSecrets:
- name: binarly-registry
```
### Ingress
`basedomain` is base domain name for Binarly Transparency Platform:
```yaml theme={null}
basedomain: "binarly.domain.com"
```
To configure the ingress, just tweak the following parameters:
```yaml theme={null}
ingress:
# @schema
# type: boolean
# @schema
# -- Enable ingress for the application
enabled: false
# @schema
# type: string
# @schema
# -- Ingress class name to use
className: "nginx"
# @schema
# type: object
# properties:
# nginx:
# type: object
# @schema
# -- Annotations for the ingress resource
annotations:
nginx.ingress.kubernetes.io/proxy-body-size: 5000m
tls:
# @schema
# type: boolean
# default: false
# @schema
# -- Enable TLS for the ingress resource
enabled: false
# @schema
# type: boolean
# default: false
# @schema
# -- Use cert-manager for TLS certificate management
useCertManager: false
# @schema
# type: string
# default: ""
# @schema
# -- Name of the TLS secret to use (if not using cert-manager)
secretName: ""
# -- Only applicable if useCertManager is enabled
clusterIssuer:
# @schema
# type: string
# default: letsencrypt
# @schema
# -- Name of the cluster issuer
name: letsencrypt
# @schema
# type: object
# @schema
# -- Extra ingress annotations for cert-manager
annotations:
cert-manager.io/cluster-issuer: letsencrypt
# @schema
# type: object
# additionalProperties: true
# @schema
# -- Issuer configuration for cert-manager
issuer:
acme:
email: ssl@binarly.io
privateKeySecretRef:
name: letsencrypt-dash-acct-key
server: https://acme-v02.api.letsencrypt.org/directory
solvers:
- http01:
ingress:
class: nginx
```
Also, from the previous configuration for the ingress, you can select if you want to use a custom TLS certificate, or to use `cert-manager` with the `Let's Encrypt` known as `ACME` by setting to `true` the key `useCertManager`.
`cert-manager` suppors many certificate provider issuers and not only `ACME` as [we can see from the list here](https://cert-manager.io/docs/configuration/issuers/).
You can tweak the `issuer` section to match any of the `cert-manager` issuers providers to be able to customize to your specific settings.
Don't forget to configure the keycloak ingress (ensure, for the `hostname` to start with `auth` and the **`basedomain`** you have configured before):
```yaml theme={null}
keycloak:
# @schema
# type: string
# @schema
# -- Name of the keycloak hostname to use. Ensure it matches with keycloakHelmChart.ingress.hostname.
hostname: "auth"
keycloakHelmChart:
chart:
values:
ingress:
# @schema
# type: boolean
# @schema
# -- Enable ingress for the application.
enabled: true
# @schema
# type: string
# @schema
# -- Ingress class name to use. For now only nginx is supported.
ingressClassName: nginx
# @schema
# type: boolean
# @schema
# -- Enable tls for the application.
tls: true
# @schema
# type: string
# @schema
# -- Name of the keycloak hostname to use. Ensure it matches with your basedomain.
hostname: "auth.binarly.domain.com"
# @schema
# type: object
# additionalProperties: true
# @schema
# -- Issuer annotations for the cluster.
annotations:
cert-manager.io/cluster-issuer: letsencrypt
```
If you are using a custom `clusterIssuer.issuer` just ensure to change the `ingressAnnotations` for both `clusterIssuer.ingressAnnotations` and `keycloakHelmChart.chart.values.annotations` to match with the new cerfiticate provider.
Currently, we expect both Binarly `dashboard` and `auth` to use the same `basedomain`. If you have your own Certifcate Authority, you'll need your own certificates for `dashboard.{{basedomain}}` and `auth.{{basedomain}}`.
### Role-Based Access Control (RBAC)
By default all access is managed via Keycloak. To enable RBAC, you can set the following values:
```yaml theme={null}
auth:
enableRBAC: true
enableRBACMiddleware: true
dashboard:
appConfigData:
features:
rbac: true
```
To read more about RBAC in the Binarly application, please see the [dedicated page](../../user-guides/rbac/roles).
### Air Gapped Environment
The Binarly Application will work in an air-gapped environment with a few caveats:
* There must be an internal registry capable of hosting images and charts.
* Chart addresses must be updated to use the internal registry.
* Image repository fields must be overwritten to use the internal registry.
* One component of the Binarly Application (Vulnerability Database) requires internet access to fetch vulnerability data.
#### Internal Registry
The registry in use should be populated with the contents of the private Binarly registry provided by Customer Success. The exact contents will be communicated prior to the installation.
#### Chart and Image Addresses
The chart address need to be updated in two places:
1. The `repositories` section of the `helmfile.d/*.yaml.gotmpl` file.
2. In the `envrc.local` file.
#### Vulnerability Database
The Vulnerability Database component of the Binarly Application requires internet access to fetch vulnerability data. This can be achieved by setting up a proxy server that allows the Vulnerability Database to access the internet, and passing this config in `k8s/apps/binarly/values.yaml.gotmpl`:
```yaml theme={null}
vdb:
env:
http_proxy: "http://proxy:port"
https_proxy: "http://proxy:port"
```
# Configure Third-Party Charts
The Binarly Installation comes with a set of third-party charts, more information in [considerations](/on-prem/v2/considerations#third-party-charts). These charts are configured in the `k8s/apps/{chart name}` directory.
## ArgoCD
### Improve password security for admin user
By default, and if the Helm chart values are not changed from default settings, ArgoCD will create automatically the initial `admin` user with the following credentials:
* Username: `admin`
* Password: A randomized string of 10 characters.
The password secret is stored in the `argocd` namespace within the following secret name: `argocd-initial-admin-secret`. We recommend though, to change the password of the account to improve the security settings of your cluster with a size of 32 characters.
To do so there are two ways:
#### Configure ArgoCD Helm chart
The other option is to directly configure the ArgoCD Helm chart, to deploy it with our password. We can do it like it follows:
1. Configure the `k8s/apps/argocd/values.yaml` to include a hashed password like it follows (ensure you have installed `htpasswd` and `openssl` cli tools):
```yaml theme={null}
configs:
secret:
# -- Bcrypt hashed admin password
## Argo expects the password in the secret to be bcrypt hashed. You can create this hash with
## export ARGOCD_PASSWORD="$(openssl rand -base64 32)"
## htpasswd -nbBC 15 "" "${ARGOCD_PASSWORD}" | tr -d ':\n' | sed 's/$2y/$2a/'
## and copy the resulting string inside `argocdServerAdminPassword`
argocdServerAdminPassword: "{bcrypt hashed password from htpasswd command}"
```
2. Ensure you save the `$ARGOCD_PASSWORD` safely, otherwise you won't be able to access ArgoCD with the `admin` credentials, unless you redeploy the chart.
3. Once ArgoCD is running and deployed in your Kubernetes cluster, the password secret is stored inside the `argocd-secret` (instead of the `argocd-initial-admin-secret` secret).
```bash theme={null}
kubectl get secret argocd-secret -n argocd -o jsonpath="{.data.admin\.password}" | base64 -d
```
What happens if I forgot my admin password?
In this particular case, you can always generate a new `admin` password, update the `k8s/apps/argocd/values.yaml` and perform a `helmfile apply --selector name=argocd` to update your ArgoCD instance with the fix.
#### Use ArgoCD CLI
This entails deploying ArgoCD (by just following this guide) and once up and running:
1. Install the ArgoCD CLI [on your system as per the official docs guide](https://argo-cd.readthedocs.io/en/stable/getting_started/)
2. Connect [ArgoCD CLI to your ArgoCD instance](https://argo-cd.readthedocs.io/en/stable/getting_started/#5-register-a-cluster-to-deploy-apps-to-optional)
3. Use the `argocd account update-password` CLI command [as stated in their docs](https://argo-cd.readthedocs.io/en/stable/user-guide/commands/argocd_account_update-password/).
What happens if I forgot my admin password? [This guide will help you to troubleshoot it](https://argo-cd.readthedocs.io/en/stable/faq/#i-forgot-the-admin-password-how-do-i-reset-it).
### Configuring ArgoCD Ingress with Ingress-Nginx and TLS
There are two main approaches to configure the ingress:
#### Option 1: SSL-Passthrough
This method allows exposing the Argo CD API server with a single ingress rule and hostname:
1. Open `k8s/apps/argocd/values.yaml`
2. Add or modify the `server.ingress` section:
```yaml theme={null}
server:
ingress:
enabled: true
ingressClassName: nginx
hostname: argocd.binarly.domain.com
annotations:
nginx.ingress.kubernetes.io/ssl-passthrough: "true"
nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
tls: true
```
3. Ensure the [nginx-ingress-controller is running with the `--enable-ssl-passthrough` flag](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#ssl-passthrough). Modify the `k8s/apps/ingress-nginx/values.yaml` to contain:
```yaml theme={null}
controller:
extraArgs:
enable-ssl-passthrough: true
```
#### Option 2: SSL Termination at Ingress Controller
For this option, you need to provide your own TLS certificate.
1. Open `k8s/apps/argocd/values.yaml`
```yaml theme={null}
server:
ingress:
enabled: true
ingressClassName: nginx
hosts:
- argocd.binarly.domain.com
annotations:
nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
nginx.ingress.kubernetes.io/backend-protocol: "HTTP"
tls:
- hosts:
- argocd.binarly.domain.com
secretName: argocd-ingress-http
```
2. Enable insecure mode for the ArgoCD server:
```yaml theme={null}
params:
server.insecure: true
```
ArgoCD supports more configuration options to configure the ingress.
[We recommend you visiting ArgoCD official documentation guide for more information](https://argo-cd.readthedocs.io/en/stable/operator-manual/ingress/).
## MetalLB
1. Include into the `repositories` list the Helm registry:
```yaml theme={null}
repositories:
- name: metallb
url: "https://metallb.github.io/metallb"
```
2. Now, add the chart to the list of `releases`:
```yaml theme={null}
releases:
- name: metallb
namespace: metallb
createNamespace: true
chart: metallb/metallb
version: "0.14.8"
labels:
name: metallb
kind: base
values:
- ./k8s/apps/metallb/values.yaml
```
3. Create the folder and the file at the path `./k8s/apps/metallb/values.yaml`.
4. Customize the `values.yaml` [according to your necessities](https://metallb.universe.tf/configuration/) by following MetalLB instructions.
5. Continue with the rest of the instructions.
# Considerations
Source: https://docs.binarly.io/on-prem/v2/considerations
## Why Kubernetes?
[Kubernetes](https://kubernetes.io/) is a container orchestration tool that helps you manage deployments using declarative configuration files called manifests. Kubernetes provides a standardized way of achieving the following:
* High availability
* Disaster recovery
* Scalability
### Relevant Kubernetes Resources
If you're new to Kubernetes, here are some starting resources to get you up to speed:
* [Kubernetes Documentation](https://kubernetes.io/docs/home/)
* [Kubernetes Basics](https://kubernetes.io/docs/tutorials/kubernetes-basics/)
* [Kubernetes Networking Concepts](https://kubernetes.io/docs/concepts/services-networking/)
* [Persistent Volumes in Kubernetes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)
* [Kubernetes from Zero to Hero](https://www.youtube.com/watch?v=X48VuDVv0do)
Binarly On-Prem can be deployed on both managed Kubernetes services and bare-metal kubernetes environments. Each option has its own advantages / disadvantages:
## Managed Kubernetes Services
Managed Kubernetes services, offered by major cloud providers, can simplify deployment and maintenance. Benefits include:
* Easier deployment and scaling
* Automated control plane maintenance
* Built-in health monitoring and repairs
However, you retain responsibility for deploying and maintaining Binarly On-Prem on the worker nodes. Some popular options include:
* Amazon Elastic Kubernetes Service (EKS)
* Google Kubernetes Engine (GKE) \[^1]
* Microsoft Azure Kubernetes Service (AKS)
When using cloud providers, ensure that your cluster configuration meets or exceeds the hardware requirements specified below.
## Bare-Metal Kubernetes
Deploying on bare-metal environments offers:
* Complete control over the entire stack
* Ability to fine-tune configurations
* Potential cost savings for large-scale deployments
Consider your specific needs, expertise, and resources when choosing between these options.
### Kubernetes Distributions
There are [many distributions available to install Kubernetes](https://nubenetes.com/matrix-table/). For self-hosted options, we recommend two for their simplicity and sane default settings:
* [k3s](https://k3s.io/)
* [rke2](https://docs.rke2.io/)
But also, more enterprise-ready options are fine too:
* [VmWare Tanzu](https://tanzu.vmware.com/platform)
* [RedHat OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift)
* [Rancher](https://www.rancher.com/)
## Kubernetes Cluster Considerations
While this guide focuses on worker node specifications, it's important to note that a functional Kubernetes cluster also requires properly configured master nodes (known as the Control Plane). The requirements for master nodes can vary significantly depending on:
* The size of your cluster
* Your chosen Kubernetes distribution
* High availability requirements
* The specific needs of your environment
We recommend consulting the documentation of your chosen Kubernetes distribution for guidance on sizing master nodes appropriately for your use case.
## Local Testing
For local testing purpose, we recommend using:
* [minikube](https://minikube.sigs.k8s.io/)
* [kind](https://kind.sigs.k8s.io/).
Both tools allow you to run Kubernetes clusters on your local machine, which is perfect for testing and familiarizing yourself with Binarly On-Prem before deploying to a production environment.
\[^1]: Our test cluster in Google Cloud Platform (GCP) uses c3-standard-8 instances (8 vCPUs, 32 GB memory) for worker nodes, which has shown good performance for testing purposes. Your specific requirements may vary based on your workload and scale.
## Hardware Requirements
For Binarly On-Prem, here are our recommended specifications for Kubernetes Worker Nodes:
| Node Type | Quantity | CPU | Memory | Storage | Network |
| ----------- | -------- | --------- | -------- | ---------- | ------- |
| Worker Node | 1-3 | 4-8 vCPUs | 16-32 GB | 100 GB SSD | 1 Gbps |
| Tools Node | 1-3 | 64 vCPUs | 512 GB | 100 GB SSD | 1 Gbps |
The Binarly Scanner is the component with the highest demands in terms of memory and CPU. We recommend allocating the resources in the table above, but scanner requirements can vary hugely between different image types.
## Kubernetes Requirements
Binarly On-Prem requires a Kubernetes cluster with the following components:
* A Storage Class for Persistent Volumes
* An Ingress Controller
* A route to the cluster
* A domain
* Three subdomain names for the components (The names can be customised):
* Dashboard (Main application)
* Keycloak (Authentication)
* Minio (Object Storage)
* Certificates for the domain names
## Scanner Requirements
The scanning tools run as Kubernetes Jobs on the system and will ideally be run on a separate node group. These jobs run in parallel and therefore can be resource intensive, depending on the subject of the scan.
### Parallel Scans
The Scanner deployment will run as many scans in parallel as there are Scanner pods. This is controlled using `replicas` in the values file:
```yaml theme={null}
server:
scanner:
replicas: 4
```
### Scan Resource Requests
The Binarly scan is made up of multiple seperate jobs that run in parallel. The resources are set in the values file and are shown here with the default values:
```yaml theme={null}
server:
scanner:
jobs:
resources:
requests:
cpu: 2000m
memory: 8Gi
limits:
cpu: 64000m
memory: 512Gi
```
Due to the complexity of the scans, the resource requests and limits are set to a high value. This is to ensure that the scans run as quickly as possible. The values can be adjusted to suit your needs, but we recommend keeping the requests and limits as high as possible and deploying these jobs on a different node group. The actual resoucre requirement varies greatly on a per-scan basis.
### Setting Up Job Distribution
The Jobs accept common Kubernetes configuration to spread the load across the cluster:
```yaml theme={null}
server:
scanner:
jobs:
toleration: See https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/ for setup
requiredPodAntiAffinity: See https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity for setup
nodeSelector: See https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector for setup
```
### Scanner Storage Requirements
By default, each scan job requests 80GB of storage. This is configurable in the values file:
```yaml theme={null}
server:
scanner:
jobs:
storageClassName: #The storage class available on your system. We suggest using a storageClass with the `reclaimnPolicy` set to `Delete`.
tempPVCForToolsStorageRequest: 80Gi # The size of the PVC for the tools. This PVC is per tool, and is roughly 1.25TB per scan using default values.
tempPVCForSymbolsStorageRequest: 1Gi # The size of the PVC for symbols jobs.
```
## Data Requirements
Binarly On-Prem requires a persistent storage backend comprising of PostgreSQL Databases and Object Storage. We recommend deploying these outside of the Binarly On-Prem cluster for better performance and reliability, but can deploy these as part of the installation.
For object storage, we support:
* Amazon S3
* Google Cloud Storage
* MinIO
For PostgreSQL we support version 16 and above.
### Using the Built-in Data System
Binarly On-Prem includes a built-in data plane for small-scale deployments. This data plane is suitable for testing and evaluation purposes, but we recommend using external storage for production deployments.
| Component | Storage Type | Default Storage Size | Number of Volumes |
| --------------------------- | ----------------- | -------------------- | ----------------- |
| VDB and Keycloak PostgreSQL | Persistent Volume | 20 GB | 1 |
| Server PostgreSQL | Persistent Volume | 100 GB | 1 |
| MinIO | Persistent Volume | 100 GB | 6 |
The Storage Size is dependent on the number of scans and the size of the images being scanned. The above values are a starting point and should be adjusted based on your specific requirements.
We recommend using a Storage Class that retains the underlying volume in case of deletion.
### Using External Data Systems
Details can be injected into the Binarly deployments using secrets in the deployment namespace. The secrets are passed to each component using the following values:
#### Databases
* Server:
```yaml theme={null}
server:
postgresql:
useExternalDatabase: true # Set to true to use an external database
connection:
passwordSecretName: server-database-connection # The name of the secret
passwordSecretKey: password # The key that contains the information required
usernameSecretName: server-database-connection
usernameSecretKey: username
hostSecretName: server-database-connection
hostSecretkey: host
databaseSecretName: server-database-connection
databaseSecretKey: database
```
* VDB:
```yaml theme={null}
vdb:
postgresql:
connection:
passwordSecretName: vdb-database-connection # The name of the secret
passwordSecretKey: password # The key that contains the information required
usernameSecretName: vdb-database-connection
usernameSecretKey: username
hostname: my-host.com
database: my-database
```
* Keycloak:
```yaml theme={null}
externalDatabase:
existingSecret: vdb-database-connection
existingSecretHostKey: host
existingSecretPortKey: port
existingSecretUserKey: username
existingSecretDatabaseKey: database
existingSecretPasswordKey: password
```
#### Object Storage
Object storage is used to:
* Host the files used for vulnerability discovery
* Store images and other artifacts
#### AWS S3
There needs to be a secret called `artefacts-bucket-credentials` with the following keys:
```yaml theme={null}
AWS_ACCESS_KEY_ID: my-access
AWS_SECRET_ACCESS_KEY: my-secret
```
The values config for VDB:
```yaml theme={null}
vdb:
artefactsBucket: my-bucket
artefactsBucketConfig:
type: s3
region: us-east-1
endpoint: s3.amazonaws.com
```
The other buckets should have a service account with the following permissions:
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": [
"arn:aws:s3:::my-bucket",
"arn:aws:s3:::my-bucket/*"
]
}
]
}
```
then this setting in the values for server:
```yaml theme={null}
server:
buckets:
images: "my-images-bucket" # These can also be one bucket with different paths
store: "my-store-bucket"
symbols: "my-symbols-bucket"
serviceAccount:
annotations:
eks.amazonaws.com/role-arn: my-role-arn
```
#### GCS
There needs to be a secret called `artefacts-bucket-credentials` with the following keys:
```yaml theme={null}
SERVICE_ACCOUNT_KEY: my-credentials
```
The values config for VDB:
```yaml theme={null}
vdb:
artefactsBucket: my-bucket
artefactsBucketConfig:
type: gcs
```
The other buckets should have a service account with the following permissions:
* objectViewer
* objectUser
* objectCreator
```yaml theme={null}
server:
buckets:
images: "my-images-bucket" # These can also be one bucket with different paths
store: "my-store-bucket"
symbols: "my-symbols-bucket"
serviceAccount:
annotations:
iam.gke.io/gcp-service-account: my-service-account
```
## Third-Party Charts
The Binarly Installation comes with a set of third-party charts that are used to support the application. While these are all optional, the installation automates set-up. These charts are:
### ArgoCD (Semi-Optional)
[ArgoCD](https://argoproj.github.io/argo-cd/) is a declarative, GitOps continuous delivery tool for Kubernetes. It allows you to deploy applications to your Kubernetes cluster using Git and Helm (among other things). The Binarly application is delivered as an app-of-apps.
### Secretsgen Controller (Semi-Optional)
[Secretgen Controller](https://github.com/carvel-dev/secretgen-controller) generates secrets from a template. This is used to generate the secrets required for the Binarly application.
### Keycloak (Required)
[Keycloak](https://www.keycloak.org/) is an open-source identity and access management solution. This is used to manage the authentication for the Binarly application.
### Zalando Postgres Operator (Optional)
[Zalando Postgres Operator](https://postgres-operator.readthedocs.io/en/latest/) is a Kubernetes operator for managing PostgreSQL clusters. This is used to manage the PostgreSQL databases required for the Binarly application if required.
### MinIO Operator (Optional)
MinIO-Operator]\([https://min.io/docs/minio/kubernetes/upstream/operations/installation.html](https://min.io/docs/minio/kubernetes/upstream/operations/installation.html)) is a Kubernetes operator for managing MinIO clusters that mimic AWS S3 object storage. This is used to manage the MinIO cluster if required.
### Nginx Ingress Controller (Optional)
[Nginx Ingress Controller](https://kubernetes.github.io/ingress-nginx/) is an Ingress controller that uses ConfigMap to store the Nginx configuration. This is can be used to manage ingress to the cluster.
### Cert Manager (Optional)
[Cert Manager](https://cert-manager.io/docs/) is a Kubernetes operator for managing TLS certificates. This is used to manage the certificates for ingress if required.
# Installation
Source: https://docs.binarly.io/on-prem/v2/installation
# Overview
This repository contains the installer for Binarly On-Prem. The installer uses Helmfile and various Helm charts to set up all necessary components.
# Prerequisites
* Access to a Kubernetes cluster (at least with version `1.29.0` or newer).
* `kubectl` configured to interact with your cluster.
* `helm` and `helmfile` installed.
* A Linux, macOS, or Windows with WSL enabled.
* Access credentials for Binarly's Artifact Registry (provided with the installer).
* A domain name, like "binarly.domain.com".
# Dependencies
The following table lists the exact dependencies known to work and necessary for the Binarly On-Prem Installer:
| Dependency | Description | Minimum Version | Installation Instructions |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------- |
| [helmfile](https://helmfile.readthedocs.io/en/stable/) | A declarative specification for deploying Helm charts | 0.162.0 | [Helmfile Installation](https://helmfile.readthedocs.io/en/latest/#installation) |
| [helm](https://github.com/helm/helm) | The Kubernetes package manager | 3.15.0 | [Helm Installation](https://helm.sh/docs/intro/install/) |
| [helm-diff](https://github.com/databus23/helm-diff) | A Helm plugin that shows a diff explaining what a Helm upgrade would change | 3.9.5 | [Helm-diff Installation](https://github.com/databus23/helm-diff#install) |
| [helm-secrets](https://github.com/jkroepke/helm-secrets) | A Helm plugin that helps manage secrets with Git workflows and store them securely | 4.6.0 | [Helm-secrets Installation](https://github.com/jkroepke/helm-secrets/wiki/Installation) |
## Checking Dependencies are Installed Correctly
To ensure all dependencies are installed correctly, you can run the following commands:
```bash theme={null}
helmfile --version
helm version
helm plugin list
```
> \[!NOTE]
> Make sure the versions of the installed dependencies meet or exceed the minimum versions specified in the table above.
# Unpacking the Installer
1. Unpack the provided `tgz` file containing the Binarly On-Prem Installer:
```bash theme={null}
tar -xzvf binarly-installer.tgz
cd binarly-installer
```
2. Verify the contents match the following directory structure:
```console theme={null}
binarly-installer
├── .envrc.local-template
├── .gitignore
├── helmfile.yaml.gotmpl
├── k8s
│ └── apps
│ ├── argocd
│ │ └── values.yaml
│ ├── binarly
│ │ └── values.yaml.gotmpl
│ ├── binarly-secrets
│ │ └── values.yaml.gotmpl
│ ├── cert-manager
│ │ └── values.yaml
│ ├── ingress-nginx
│ │ └── values.yaml
│ ├── minio-operator
│ │ └── values.yaml
│ ├── postgres-operator
│ │ └── values.yaml
│ ├── secretgen-controller
│ │ └── values.yaml
│ └── trust-manager
│ └── values.yaml
├── README.md
└── secrets
├── .gitkeep
└── binarly-registry-credentials
```
# Directory Structure
The installer package contains the following key files and directories:
* `.envrc.local-template`: Template for environment configuration file with required env variables. Should be renamed/copied to `.envrc.local`.
* `helmfile.yaml.gotmpl`: Helmfile template for deployment of the Kubernetes helm charts.
* `k8s/apps/`: Contains configuration for various applications necessary to deploy Binarly On Prem to Kuberentes (ArgoCD, Binarly, cert-manager, etc.).
* `secrets/`: Directory for storing sensitive information (i.e: the Artifact Registry credentials).
## Kubernetes Helm Chart Configuration
The file `helmfile.yaml.gotmpl` contains all of the charts to install Binarly On-Prem on your Kubernetes cluster. There are two main groups of charts listed:
### External Dependencies
Binarly On-Prem depends on the following projects:
* [ArgoCD](https://argo-cd.readthedocs.io/en/stable/)
* [MinIO-Operator](https://min.io/docs/minio/kubernetes/upstream/operations/installation.html)
* [Secretgen Controller](https://github.com/carvel-dev/secretgen-controller)
* [Zalando Postgres Operator](https://postgres-operator.readthedocs.io/en/latest/)
Each of these dependencies can be easily configured by just going to the `k8s/apps` directory and the name of the dependency. Default settings should be more than enough to have
a working cluster but, we recommend configuring each dependency to meet your requirements and policies towards security and best practices. We offer below some advice to some of them.
### Configuring ArgoCD
By default, ArgoCD does not need any configuration. There are optional steps in the [configuration document](./configuration/#binarly-secrets).
## Installation
### Configure Environment Variables
1. Enter the `binarly-installer` directory.
2. Rename `.envrc.local-template` to `.envrc.local`:
```bash theme={null}
mv .envrc.local-template .envrc.local
```
3. Put your Binarly Artifact Registry credentials inside a file called `binarly-registry-credentials` in a `secrets/` directory.
Treat this file with maximum security as it grants access to your personal Artifact Registry.
4. Edit `.envrc.local` and you will see the following environment variables:
```bash theme={null}
# Binarly Registry
export BINARLY_REGISTRY_HOST="us-central1-docker.pkg.dev"
export BINARLY_REGISTRY_PATH="binarly-tenant-1"
export BINARLY_REGISTRY_FQDN="${BINARLY_REGISTRY_HOST}/${BINARLY_REGISTRY_PATH}"
export BINARLY_REGISTRY_USERNAME="_json_key_base64"
export BINARLY_REGISTRY_PASSWORD=$(cat $PWD/secrets/binarly-registry-credentials)
# Binarly Secrets
export BINARLY_SECRET_NVD_API_KEY=""
export BINARLY_SECRET_SERVER_INTEGRATION_SECRET=""
```
Ensure your `$BINARLY_REGISTRY_HOST` and `$BINARLY_REGISTRY_PATH` contains the correct Artifact Registry connection details (the previous ones are just placeholder values).
5. Source the `.envrc.local` to have the variables available to your shell session:
```bash theme={null}
source .envrc.local
```
If you make a change again to the `.envrc.local` file, ensure you run again the command to update your variables in your shell session.
You can verify everything is correctly setup correcty by issuing `echo` commands to test the output of the previous variables on your terminal.
```bash theme={null}
% echo $BINARLY_REGISTRY_HOST
us-central1-docker.pkg.dev
echo $BINARLY_REGISTRY_PATH
binarly-tenant-1
% echo $BINARLY_REGISTRY_FQDN
us-central1-docker.pkg.dev/binarly-tenant-1
echo $BINARLY_REGISTRY_USERNAME
_json_key_base64
echo $BINARLY_REGISTRY_PASSWORD
eyJ0eXBlIjoic2VydmljZV9hY2NvdW50IiwicHJvamVjdF9p.......
echo $BINARLY_SECRET_NVD_API_KEY
awea...
echo $BINARLY_SECRET_SERVER_INTEGRATION_SECRET
uyyal...
```
### Configure binarly-secrets chart
Please see the [configuration](./configuration/#binarly-secrets) section for more information on the secrets chart.
1. Ensure you have added to the `.envrc.local` the following variables for the secrets:
* `BINARLY_SECRET_NVD_API_KEY`: NVD API Key.
* `BINARLY_SECRET_SERVER_INTEGRATION_SECRET`: Encryption Key for Jira Integration setup. Must be random 32 character string.
### Configure binarly chart
Please see the [configuration](./configuration/#binarly-chart) section for more information on the secrets chart.
1. Edit `k8s/apps/binarly/values.yaml.gotmpl`, make sure to specify:
* `basedomain`: Base domain name at which Binarly Transparency Platform should be available on the local network.
* `keycloakHelmChart.chart.values.ingress.hostname`: Should be `"auth.{{basedomain}}"` with `basedomain` substituted with Base domain name.
* `clusterIssuer`: Certificate Issuer to configure cert-manager to issue TLS certificates for the chosen domain name (for ex. "dashboard.binarly.domain.com").
### Install helm charts
Once everything is configured, let's install Binarly On-Prem on your Kubernetes cluster. To do so, first let's do it in batches. If we have a look to the `helmfile.yaml.gotmpl` file, we can discover we have two kind of helm charts defined:
* Dependencies (or base) charts: All extra necessary charts for Binarly to run.
* binarly: Charts specific for Binarly.
With helmfile, we can use the concept of `selectors`, i.e: this allows to select group of chars inside the `relase` entry.
1. We will start first those base dependencies on the cluster, to do so:
```bash theme={null}
helmfile sync --selector kind=base
```
If everything goes well you should see on the terminal that helm is installing ArgoCD, postgres-operator, etc on the Kubernetes cluster (all of the `releases` inside the `helmfile.yaml.gotmpl` with a label of `kind=base`).
2. Now it's time to install the second group, the Binarly charts. To do so:
```bash theme={null}
helmfile sync --selector kind=binarly
```
And as before, it will proceed with the installation of the `secrets` and `binarly` charts.
#### Sync Binarly ArgoCD applications
ArgoCD will be installed on the `argocd` namespace, and if it's using the default settings, we can do the following for displaying the UI (otherwise if we have added an Ingress, we can use the domain assigned to ArgoCD):
1. Obtain the credentials (from `argocd-initial-admin-secret` if you haven't changed the ArgoCD password or from `argocd-secret`):
ArgoCD default password:
```bash theme={null}
kubectl get secret argocd-initial-admin-secret -n argocd -o jsonpath="{.data.password}" | base64 --decode
```
2. And now do a port-forward:
```bash theme={null}
kubectl port-forward svc/argocd-server 9090:80 -n argocd
```
3. Navigate with your browser to `http://localhost:9090` and fill the credentials with user `admin` and password the one you obtained before. It should list all of the Binarly applications.
4. We can proceed to sync the applications in the following order:
1. `minio-buckets` (wait for it to be `healthy` in ArgoCD).
2. `fetch-artefacts` (wait for it to be `healthy` in ArgoCD).
3. `common` (don't wait for it to be `healthy` in ArgoCD and deploy `keycloak`).
4. `keycloak` (wait for `common` and `keycloak` to be healthy in ArgoCD).
5. `dashboard` (wait for it to be `healthy` in ArgoCD).
6. `server` (wait for it to be `healthy` in ArgoCD).
When syncing `common` there's a strict dependency on `keycloak`. So better to sync both `applications` at the same time. First sync `common` and whilst is still syncing, just sync `keycloak`. Once both are green, then proceed to `fetch-artefacts`.
Once all of the ArgoCD Apps are synced, Binarly should be running at the URL of choice.
## Extra Helm chart additions
There are additional projects that can be used alongside the Binarly application:
* [Cert-Manager](https://cert-manager.io/)
* [Ingress-Nginx](https://kubernetes.github.io/ingress-nginx/)
* [Trust-Manager](https://cert-manager.io/docs/trust/trust-manager/)
Your environment may require more charts to be installed. These can be added to the `helmfile.yaml` file and a corresponding `values.yaml` file in the `k8s/apps` directory.
# Removal
Source: https://docs.binarly.io/on-prem/v2/uninstallation
To remove and clean the cluster, we need to do two steps:
1. Delete all ArgoCD apps. To do so, just port-forward to it as we did on the previous step and start deleting each app. It will clear everything.
2. Use helmfile to delete all installed charts.
The command to do it:
```bash theme={null}
helmfile destroy
```
And this will remove all charts installed by helmfile.
This is a destructive operation. It will destroy *everything* and data loss will happen unless you have backed up the data stores. Excercise this command with care.
# Configuration
Source: https://docs.binarly.io/on-prem/v3/configuration
# Configure Binarly charts
This page describes how to configure the Binarly charts for your deployment. The configuration is done through a values file that is passed to the Helm chart during installation, and secrets set up prior to the installation.
## Binarly Secrets
The following table details secrets that are **required** by the platform. It is recommended to use a more secure method of managing the manual secrets such as the External Secrets Operator or Sealed Secrets.
The secrets and their uses are as follows (This list is not exhaustive):
| Secret Name | Description | Usage | Deployment |
| ---------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| keycloak | Keycloak admin user credentials | Used by Keycloak for authentication | Automatic |
| keycloak-database-connection | Keycloak database connection details | Used by Keycloak to connect to the database. If using the built-in database, these details are automatically managed. | Automatic |
| server-database-connection | Server database connection details | Used by the Binarly Server to connect to the database. If using the built-in database, these details are automatically managed. | Automatic |
| nvd-api-key | NVD API key for accessing the National Vulnerability Database | Used by the vulnerability database to fetch vulnerability data. Provided by customer support. | Manual |
| binarly-registry | Docker registry credentials for Binarly images | Used to pull Binarly images from the provided private registry. | Manual |
| docker-login-credentials | Docker registry credentials for pulling images | Used to pull images from the specified Docker registry. | Manual |
| server-integration-secret | Integration secret for the Binarly Server | Used by the Binarly Server. | Manual |
### Deploying the Secrets
Secrets should be deployed prior to installation. Any method to deploy the secrets will work and the following are provided as examples.
Additional resources (Like ExternalSecrets) can be passed using the `extraResources` value, see [here](./configuration#extra-resources) for configuration.
It is recommended to use a more secure method of managing the secrets such as the External Secrets Operator or Sealed Secrets. To detail the structure of the secrets, here are examples of how to manually create the required secrets using kubernetes manifests.
```yaml theme={null}
apiVersion: v1
kind: Secret
type: Opaque
metadata:
name: nvd-api-key
data:
key:
```
```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
name: binarly-registry
type: kubernetes.io/dockerconfigjson
data:
.dockerconfigjson:
```
The Docker Config JSON can be constructed using the following template:
```json theme={null}
{
"auths": {
"": {
"username": "_json_key",
"password": "",
"email": ""
}
}
}
```
```yaml theme={null}
apiVersion: v1
kind: Secret
type: Opaque
metadata:
name: docker-login-credentials
data:
DOCKER_LOGIN_USERNAME: < _json_key, base64 encoded >
DOCKER_LOGIN_PASSWORD:
```
```yaml theme={null}
apiVersion: v1
kind: Secret
type: Opaque
metadata:
name: server-integration-secret
data:
server-integration-secret:
```
The [External Secrets Operator](https://external-secrets.io/latest/) can be used to manage secrets more securely. Here is an example of how to define an external secret for the binarly registry:
```yaml theme={null}
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
name: binarly-registry
spec:
dataFrom:
- extract:
conversionStrategy: Default
decodingStrategy: None
key: binarly-registry
metadataPolicy: None
refreshInterval: 1h
secretStoreRef:
kind: ClusterSecretStore # Or SecretStore
name: my-secret-store # The name of the secret store
target:
creationPolicy: Owner
deletionPolicy: Retain
name: binarly-registry # The name of the secret on your secret store
```
Where the `binarly-registry` secret in your secret store contains the following JSON structure:
```json theme={null}
{
"auths": {
"": {
"username": "_json_key",
"password": "",
"email": ""
}
}
}
```
[Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) can be used to manage secrets more securely. Here is an example of how to define a sealed secret for the binarly registry:
```yaml theme={null}
apiVersion: bitnami.com/v1alpha1
kind: SealedSecret
metadata:
name: binarly-registry
spec:
encryptedData:
.dockerconfigjson:
template:
type: kubernetes.io/dockerconfigjson
immutable: true
```
The encrypted docker config JSON would look like the following before encryption:
```json theme={null}
{
"auths": {
"": {
"username": "_json_key",
"password": "",
"email": ""
}
}
}
```
## Values
A minimal deployment requires setting the following values in another file, e.g. `specific-values.yaml`:
**Please do not uses these values as-is, they must be adapted to your environment.**
```yaml theme={null}
global:
imagePullSecrets:
- name: binarly-registry # The name of the secret containing the Binarly registry credentials
storageClassName: standard # The storage class to use for persistent volumes for the application
ingressClassName: tailscale # The ingress class to use for the application
basedomain: binarly.io # The base domain for the application
dashboard:
hostname: "dashboard" # The hostname for the Binarly Dashboard
keycloak:
hostname: "keycloak" # The hostname for Keycloak
bucketsConfig:
publicEndpoint: https://minio-api.binarly.io # The public endpoint for MinIO, if using the built-in data storage option
keycloak:
ingress:
hostname: "keycloak.binarly.io" # Unfortunately this has to be set twice
scan-workflow: # Specific configuration for the scanner jobs
workflow:
storageClassName: "premium" # The storage class to use for the scanner jobs. Please ensure this storage class' reclaimPolicy is set to Delete.
nodeSelector: # The node selector to use for the scanner jobs
workload: tools
tolerations:
- effect: NoSchedule
key: workload
operator: Equal
value: tools
```
### Extra Resources
The Chart contains an `extraResources` section that allows you to deploy additional resources alongside the main chart. This can be used to deploy custom ConfigMaps, Secrets, or other Kubernetes resources that are not part of the main chart. This is useful for adding custom configurations or additional components that are not included in the chart by default, and are specific to your environment.
For example:
```yaml theme={null}
extraResources:
test:
apiVersion: v1
kind: ConfigMap
metadata:
name: test-config
data:
key: value
externalSecrets:
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
name: my-external-secret
spec:
backendType: secretsManager
data:
- key: my-secret-key
name: my-secret-name
```
This will create a ConfigMap named `test-config` and an ExternalSecret named `my-external-secret`. This is an alternative to creating a wrapper chart around this chart.
## Upgrading
The chart follows the [semantic versioning](https://semver.org/#summary) convention so any breaking changes will be reflected in the major version number. Any other changes should be backwards compatible.
To prevent constant major version updates some values are deprecated but not removed. When there is a breaking change released all deprecated values will be removed and a notice posted on this readme with upgrade instructions.
Pre-upgrade, please ensure the Database is backed up. This depends on your deployment method, but if you are using the built-in PostgreSQL database, you can use the `pg_dump` command to create a backup of the database. If you are using an external database, please refer to your database provider's documentation for backup instructions.
### ArgoCD and FluxCD
Upgrades involving minor or patch versions should be carried out depending on your installation method. If you are using ArgoCD or FluxCD, the upgrade will be handled by updating the version on your Application or HelmRelease.
### Helm
If you are using Helm, you can upgrade the chart using the following command:
```bash theme={null}
helm upgrade binarly-transparency-platform oci:///charts/binarly-transparency-platform: \
-f specific-values.yaml \
--namespace binarly-transparency-platform \
--skip-crds
```
To check for differences the helm diff plagin is useful (Requires separate installation):
```bash theme={null}
helm plugin install https://github.com/databus23/helm-diff
helm diff upgrade binarly-transparency-platform oci:///charts/binarly-transparency-platform \
--version 1.2.3 \
-f specific-values.yaml \
--namespace binarly-transparency-platform
```
## Rollback
There are two rollback scenarios to consider:
### No Migrations
If the upgrade does not include any database migrations, you can simply rollback to the previous version using the following command:
```bash theme={null}
helm rollback binarly-transparency-platform --namespace binarly-transparency-platform
```
### With Migrations
Migrations are not backwards compatible so if the upgrade includes database migrations, you will need to restore the database from a backup. This can be done using the `pg_restore` command for PostgreSQL databases. If you are using an external database, please refer to your database provider's documentation for rollback instructions.
During the restore process you will need to disable the Binarly Server and VDB components to prevent them from trying to access the database while it is being restored. This can be done by setting the `server.enabled` and `vulnerability-database.enabled` values to `false` in the `values.yaml` file, or by using the `--set` flag when running the `helm upgrade` command. After this, restore the database and restart the components by setting the values back to `true` and running the `helm upgrade` command again.
## High Availability
The chart contains partial support for high availability. The following components can be deployed in a highly available configuration:
* Keycloak
* Dashboard
* VDB
To set these, use the following values:
```yaml theme={null}
keycloak:
replicaCount: 3 # The number of Keycloak replicas to deploy
dashboard:
replicaCount: 3 # The number of Dashboard replicas to deploy
reportsService:
replicaCount: 3 # The number of Reports Service replicas to deploy
vulnerability-database:
hpa:
enabled: true # Enable Horizontal Pod Autoscaler for the VDB service, defaults to three replicas
```
## Routing to the Application
### Gateway API
The Gateway API can be used to route to the application:
```yaml theme={null}
global:
httpRoutes:
enabled: true
parentRefs:
name: gateway-name
namespace: gateway-namespace
basedomain: "binarly.domain.com"
dashboard:
hostname: dashboard
keycloak:
hostname: auth
server:
ociRegistry:
hostname: registry # If using the custom rules feature
```
### Ingress
#### Legacy
Ingress resources currently provisioned from the dashboard, minio-buckets, and keycloak chart.
`basedomain` is base domain name for Binarly Transparency Platform:
```yaml theme={null}
global:
basedomain: "binarly.domain.com"
dashboard:
hostname: "dashboard" # The hostname for the Binarly Dashboard
keycloak:
hostname: "keycloak" # The hostname for Keycloak
bucketsConfig:
publicEndpoint: https://minio-api.binarly.domain.com # The public endpoint for MinIO, if using the built-in data storage option
keycloak:
ingress:
enabled: true
hostname: "keycloak.binarly.domain.com"
dashboard:
ingress:
enabled: true
minio-buckets:
minioBuckets:
ingress:
enabled: true
```
#### Consolidated
Since BTP chart version 1.58.0, consolidated ingress configuration is available. This aims to minimize complex, multi-component configuration between components of BTP
```yaml theme={null}
global:
basedomain: "binarly.domain.com"
consolidateIngressConfig: true
dashboard:
hostname: "dashboard" # The hostname for the Binarly Dashboard
keycloak:
hostname: "keycloak" # The hostname for Keycloak
bucketsConfig:
publicEndpoint: https://minio-api.binarly.domain.com # The public endpoint for MinIO, if using the built-in data storage option
ingress:
enabled: true
className: "yourIngressClassName"
dashboard:
enabled: true
name: "dashboard"
hostname: "dashboard"
minioBuckets:
enabled: true
api:
hostname: "minio-api"
console:
hostname: "minio-console"
keycloak:
enabled: true
name: "keycloak"
hostname: "keycloak.binarly.domain.com"
```
The above config will create the following ingress resources:
* `dashboard.binarly.domain.com` for the Binarly Dashboard
* `keycloak.binarly.domain.com` for Keycloak
* `minio-api.binarly.domain.com` for MinIO
## Observability
The BTP Chart emits a variety of metrics, logs, and traces to help you monitor the health and performance of the applications.
### Metrics
Metrics can be collected from prometheus metrics endpoints exposed by the various components. The following components expose metrics:
* Keycloak
* Server API
* Server Scanner
* Argo Workflows
* Minio
And can be configured using the following values:
```yaml theme={null}
server:
metrics:
enabled: true
keycloak:
metrics:
enabled: true
argo-workflows:
controller:
metricsConfig:
enabled: true
```
### Logs
Logs are output to Stdout and Stderr in JSON format by default.
### Traces
Traces are produced in OpenTelemetry format from the following components:
* Server API
* Server Scanner
And can be configured using the following values:
```yaml theme={null}
server:
traces:
enabled: true
host: Collector Host
port: Collector Port
```
## Role-Based Access Control (RBAC)
By default all access is managed via Keycloak. To enable RBAC, you can set the following values:
```yaml theme={null}
auth:
enableRBAC: true
enableRBACMiddleware: true
dashboard:
appConfigData:
features:
rbac: true
```
To read more about RBAC in the Binarly application, please see the [dedicated page](../../user-guides/rbac/roles).
## Custom Rules
To use the [Custom Rules](../../user-guides/rule-management/overview) feature in an on-premise installtion, an installation of [Harbor](https://goharbor.io/) is **required** to manage the artefacts used by the system, and the user's credentials must be available to the binarly application.
Harbor can be deployed on kubernetes using the helm chart:
```
helm repo add harbor https://helm.goharbor.io
helm install harbor harbor/harbor -f values-specific-to-your-environment.yaml
```
It is strongly suggested to use the following values as part of the user's specific values to prevent issues:
```yaml theme={null}
jobservice:
jobLoggers:
- stdout
```
With a working harbor installation, the following values can be passed to the BTP Chart to enable custom rules with substitutions to match the user's environment:
```yaml theme={null}
global:
# -- The name of the project that will be used in harbor
clusterName: harbor-project
features:
customRules: true
harbor:
# -- harbor host
host: harbor.harbor-ha.svc.cluster.local
# -- harbor insecure connection
insecure: true
# -- Name of the Kubernetes secret containing harbor username.
usernameSecretName: "harbor"
# -- Key in the secret for the harbor username.
usernameSecretKey: "username"
# -- Name of the Kubernetes secret containing harbor password.
passwordSecretName: "harbor"
# -- Key in the secret for the harbor password.
passwordSecretKey: "password"
```
The secret name and keys can be customised. The default secret looks like this:
```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
name: harbor
type: Opaque
data:
password: "A base64 encoded password"
username: "A base64 encoded username"
```
This secret will be mounted and user to interact with harbor. Please ensure:
* A user has been provisioned on the harbor instance
* The user has access to a project with a name defined in global.clusterName as above
## Air Gapped Environment
The Binarly Application will work in an air-gapped environment with a few caveats:
* There must be an internal registry capable of hosting images and charts.
* Chart addresses must be updated to use the internal registry.
* Image repository fields must be overwritten to use the internal registry.
* One component of the Binarly Application (Vulnerability Database) requires internet access to fetch vulnerability data.
### Internal Registry
The registry in use should be populated with the contents of the private Binarly registry provided by Customer Success. The exact contents will be communicated prior to the installation.
### Images
In case you wish to distribute artifacts with your chosen artifact registry, we recommend using the `helm images` plugin. Further details on this plugin can be found in [artifactHUB](https://artifacthub.io/packages/helm-plugin/images/images)
Installation of this plugin is simple as
```bash theme={null}
helm plugin install https://github.com/nikhilsbhat/helm-images
```
To get a human friendly output with all the images that you need to distribute on your end, use the following:
```bash theme={null}
helm images get . -o table -u -f .yaml
```
This output can be used to pull images from the Binarly registry and push them to your internal registry.
### Vulnerability Database
The Vulnerability Database component of the Binarly Application requires internet access to fetch vulnerability data. This can be achieved by setting up a proxy server that allows the Vulnerability Database to access the internet, and passing this config in `k8s/apps/binarly/values.yaml.gotmpl`:
```yaml theme={null}
vulnerability-database:
env:
http_proxy: "http://proxy:port"
https_proxy: "http://proxy:port"
```
By default, the Vulnerability Database updater downloads its data from Binarly’s infrastructure, outside of your cluster. The updater only reads vulnerability database files from a Binarly-managed storage location that is dedicated to your installation. No data, metadata, or telemetry is sent from your cluster back to Binarly as part of this process.
Access to this external storage is restricted to the Vulnerability Database updater only and is isolated from other components in your environment.
Example configuration:
```yaml theme={null}
vulnerability-database:
artefactsBucketConfigOverride:
enabled: true
bucketName: "your-gcs-bucket-name"
serviceAccountSecret:
name: "vdb-gcs-sa"
key: "service-account.json contents here"
```
If you prefer the Vulnerability Database to be sourced entirely from within your cluster or your own infrastructure, you can disable this override by setting the flag to off. In that case, the updater will use your globally configured internal storage instead.
```yaml theme={null}
vulnerability-database:
artefactsBucketConfigOverride:
enabled: false
```
Specifically, the Vulnerability Database files include:
* License detection metadata, used to identify open-source licenses embedded in packages and dependencies.
* cvehunt-java detection data, used to match Java artifacts (JARs, classes, and package signatures) against known vulnerabilities.
These detections cannot be performed without the Vulnerability Database files. The scanner does not generate this information dynamically or from your workload data; it relies entirely on the prebuilt Vulnerability Database content.
# Configure Third-Party Charts
The Binarly Installation comes with a set of third-party charts, more information in [considerations](./considerations#third-party-charts). These charts are configured in the `charts/{chart name}` directory.
# Considerations
Source: https://docs.binarly.io/on-prem/v3/considerations
The Binarly Transparency Platform should be deployed on a Kubernetes cluster.
# Hardware Requirements
The following hardware requirements are assumed with a single instance of the platform running scans are multiple large images in parallel, in the worst case scenario:
| Node groups | Quantity | CPU | Memory | Storage | Network |
| -------------- | -------- | --------- | -------- | ---------- | ------- |
| Default nodes | 1-3 | 2-4 vCPUs | 16-32 GB | 100 GB SSD | 1 Gbps |
| Scanning nodes | 1-3 | 64 vCPUs | 512 GB | 100 GB SSD | 1 Gbps |
Depending on the usage pattern the scan nodes can be made smaller to parallelise parts of scans. See the [Scanner Requirements](#scanner-requirements) section for more detail on scan resourcing.
The Binarly Scanner is made up of many components that have high resource requirements. The scanner should be deployed on a dedicated node group to prevent resource contention, Out Of Memory failures, and degraded performance. Additionally, a low priorityClass should be assigned to the scanner pods.
Binarly strongly recommend monitoring the resource usage of the scanner pods and using this information to right-size the the scanning node group.
The scanning node group should configured to scale down to zero nodes when no scans are being run by the cluster operator.
# Kubernetes Requirements
Binarly On-Prem requires a Kubernetes cluster with the following components:
* A Storage Class for Persistent Volumes, reclaimPolicy set to Delete. This is used during scans.
* If using Minio and Postgres, a Storage Class for Persistent Volumes with reclaimPolicy set to Retain.
* An Ingress Controller or a Gateway
* A route to the cluster
* A domain
* Three subdomain names for the components (The names can be customised):
* Dashboard (Main application)
* Keycloak (Authentication)
* Minio (Object Storage)
* Certificates for the domain names
# Scanner Requirements
The Binarly scanner runs in two distinct phases: the normalisation phase and the scan phase.
During normalisation the input file is normalised into a format that can be processed during the scan phase. This phase requires a PVC that is discarded when normalisation is complete.
The scanning phase takes the output of normalisation and processes it with several tools in parallel, using the node's ephemeral storage to store files during this process.
## Resourcing
Resource usage by the scanner components is entirely dependent on the size of the input file, number of components, and size of individual components. Generally, smaller files will use fewer resources and the size of the scanning node group can be made dramatically smaller. Larger files with large components will use more memory during a scan.
Collecting the memory and CPU metrics from scan pods will allow continuous tuning of the resources required by the scanner. It is better to overprovision and adjust down once a profile has been established.
Depending on the input files some tools may not have components to process, or alternatively have many large components to process.
### Resource Requests and Limits
The scan pods can have a global or individual Request and Limit for memory and CPU:
```yaml theme={null}
# The global requests and limits, applied to all scan pods when not explicitly overwritten
scan-workflow:
workflow:
resources:
limits:
cpu: 64000m
memory: 512Gi
requests:
cpu: 2000m
memory: 8Gi
# Explicitly overwriting the requests and limits for the detect tool
global:
scanToolsConfiguration:
detect:
resources:
limits:
cpu: 5000m
memory: 16Gi
requests:
cpu: 1000m
memory: 4Gi
```
### Analysis Code Size Limit
Analysis tools skip any binary component whose code size exceeds a configured limit. The limit is a byte count, it ships with a tested default of 209715200 bytes (displayed as 200 MB in the platform UI), and it applies to every analysis tool unless a tool overrides it:
```yaml theme={null}
scan-workflow:
workflow:
analysisCodeSizeLimit: '209715200' # Default, shown as 200 MB in the UI
# Explicitly overwriting the limit for the detect tool
global:
scanToolsConfiguration:
detect:
analysisCodeSizeLimit: '40000000' # Roughly 40MB, in bytes
```
Skipped components are reported on the image, so the effect of the configured value is visible per scan. See [Code Size Limit](/resource-center/code-size-limit) for how code size is measured and where skipped components appear.
The default was tested against the resourcing this chart ships with. Raising it brings large components back into analysis, and those components drive peak memory and scan duration, so review [Resource Requests and Limits](#resource-requests-and-limits) and [Partitioned Scans](#partitioned-scans) before changing it. Contact [Binarly Support](/user-guides/about/customer-support) if you need a higher limit for your workload.
### Partitioned Scans
If the usage pattern requires large files to be scanned, or a mixture of large and small files, the scanner can be configured to partition each normalised input and run a job in parallel per partition:
```yaml theme={null}
scan-workflow:
workflow:
scanPartitions:
partitionSize: '50000000' # Roughly 50MB, in bytes
```
Using the above configuration a 150 MB binary would be split into three partitions which are scanned in parallel. This allows the jobs that run these processes to be split across several smaller nodes.
Setting a small number for partition size and processing large binaries can cause a very large number of pods to be created, which can seriously impact the kubernetes API and Workflow Performance. The following value can be passed to Argo Workflows to limit parallelism:
```yaml theme={null}
argo-workflows: # If deployed as an all-in-one chart, omit this key if deployed separately
controller:
resourceRateLimit:
limit: 10 # limit to ten pods per creation phase
burst: 1
```
### Parallel Scans
The Scanner deployment will run as many scans in parallel as defined in values:
```yaml theme={null}
server:
scanner:
maxConcurrentFullScans: 4
```
### Scan Resource Requests
The Binarly scan is made up of multiple separate jobs that run in parallel. The resources are set in the values file and are shown here with the default values:
```yaml theme={null}
scan-workflow:
workflow:
resources:
limits:
cpu: 64000m
memory: 512Gi
requests:
cpu: 2000m
memory: 8Gi
```
Due to the complexity of the scans, the resource requests and limits are set to a high value. This is to ensure that the scans run as quickly as possible. The values can be adjusted to suit your needs, but we recommend keeping the requests and limits as high as possible and deploying these jobs on a different node group. The actual resoucre requirement varies greatly on a per-scan basis.
### Setting Up Job Distribution
The Jobs accept common Kubernetes configuration to spread the load across the cluster:
```yaml theme={null}
scan-workflow:
workflow:
nodeSelector: # The node selector to use for the scanner jobs
workload: tools
tolerations: # The tolerations to use for the scanner jobs
- effect: NoSchedule
key: workload
operator: Equal
value: tools
```
### Scanner Storage Requirements
By default, the initial normalise phase requests 80GB of storage. This is configurable in the values file:
```yaml theme={null}
scan-workflow:
workflow:
toolPvcSize: 80Gi
```
# Data Requirements
Binarly On-Prem requires a persistent storage backend comprising of PostgreSQL Databases and Object Storage. We recommend deploying these outside of the Binarly On-Prem cluster for better performance and reliability, but can deploy these as part of the installation.
For object storage, we support:
* Amazon S3
* Google Cloud Storage
* MinIO
For PostgreSQL we support version 16 and above.
## Using the Built-in Data System
Binarly On-Prem includes a built-in data plane for small-scale deployments. This data plane is suitable for testing and evaluation purposes, but we recommend using external storage for production deployments.
| Component | Storage Type | Default Storage Size | Number of Volumes |
| --------------------------- | ----------------- | -------------------- | ----------------- |
| VDB and Keycloak PostgreSQL | Persistent Volume | 20 GB | 1 |
| Server PostgreSQL | Persistent Volume | 100 GB | 1 |
| MinIO | Persistent Volume | 100 GB | 6 |
The Storage Size is dependent on the number of scans and the size of the images being scanned. The above values are a starting point and should be adjusted based on your specific requirements.
We recommend using a Storage Class that retains the underlying volume in case of deletion for the built in data system.
# Using External Data Systems
Details can be injected into the Binarly deployments using secrets in the deployment namespace.
## Databases
Binarly requires a Postgres instance version 16 or above, and connection details to that instance.
The secrets are passed to each component using the following values:
* Server:
```yaml theme={null}
server:
postgresql:
useExternalDatabase: true # Set to true to use an external database
connection:
passwordSecretName: server-database-connection # The name of the secret
passwordSecretKey: password # The key that contains the information required
usernameSecretName: server-database-connection
usernameSecretKey: username
hostSecretName: server-database-connection
hostSecretkey: host
databaseSecretName: server-database-connection
databaseSecretKey: database
```
* VDB:
```yaml theme={null}
vdb:
postgresql:
connection:
passwordSecretName: vdb-database-connection # The name of the secret
passwordSecretKey: password # The key that contains the information required
usernameSecretName: vdb-database-connection
usernameSecretKey: username
hostname: my-host.com
database: my-database
```
* Keycloak:
```yaml theme={null}
keycloak:
externalDatabase:
existingSecret: vdb-database-connection
existingSecretHostKey: host
existingSecretPortKey: port
existingSecretUserKey: username
existingSecretDatabaseKey: database
existingSecretPasswordKey: password
```
## Object Storage
Object storage is used to:
* Host the files used for vulnerability discovery
* Store images and other artifacts
### AWS S3
Authentication to S3 can be done using IRSA, PodIdentity, or access keys. Please see the AWS documentation for more details on how to set this up on your AWS cluster.
#### IRSA Using a Role Annotation
The values config for external buckets:
```yaml theme={null}
global:
buckets:
images: "my-images-bucket"
bucketsConfig:
type: s3
region: us-east-1
endpoint: s3.amazonaws.com
publicEndpoint: https://s3.amazonaws.com # The public endpoint for the S3 bucket
useIAM: true
artefactsBucketConfig:
type: s3
region: us-east-1
endpoint: s3.amazonaws.com
useIAM: true
bucketName: my-artefacts-bucket
```
The service accounts using the role need to be annotated using the following values:
```yaml theme={null}
server:
serviceAccount:
annotations:
eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/my-role
vulnerability-database:
serviceAccount:
annotations:
eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/my-role
```
#### Pod Identity
This is similar to IRSA except the annotation is not required. The service account just needs to be linked to the role using the Pod Identity mechanism detailed here: [https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html)
#### Access Keys
The access key and secret key need to be stored inside a secret in the namespace where Binarly is deployed and is not managed by the BTP chart. The following example has two secrets, `bucket-credentials` for the images bucket and `artefacts-bucket-credentials` for the artefacts bucket.
```yaml theme={null}
global:
buckets:
images: "my-images-bucket"
bucketsConfig:
type: s3
region: us-east-1
endpoint: s3.amazonaws.com
publicEndpoint: https://s3.amazonaws.com # The public endpoint for the S3 bucket
accessKeySecret:
name: "bucket-credentials"
key: "AWS_ACCESS_KEY_ID"
secretKeySecret:
name: "bucket-credentials"
key: "AWS_SECRET_ACCESS_KEY"
artefactsBucketConfig:
type: s3
region: us-east-1
endpoint: s3.amazonaws.com
bucketName: my-artefacts-bucket
accessKeySecret:
name: "artefacts-bucket-credentials"
key: "AWS_ACCESS_KEY_ID"
secretKeySecret:
name: "artefacts-bucket-credentials"
key: "AWS_SECRET_ACCESS_KEY"
```
### Permissions and CORS
The Role or User used to access the buckets needs the following permissions:
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "BinarlyPolicy",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObjectAcl",
"s3:GetObject",
"s3:ListBucket",
"s3:DeleteObject",
"s3:PutObjectAcl"
],
"Resource": [
"arn:aws:s3:::my-images-bucket",
"arn:aws:s3:::my-artefacts-bucket",
"arn:aws:s3:::my-images-bucket/*",
"arn:aws:s3:::my-artefacts-bucket/*"
]
}
]
}
```
A CORS policy must be set on the Images bucket as the application will present self-signed URLs to the user. This policy should allow the necessary origins and methods for the application to function correctly.
```json theme={null}
[
{
"AllowedHeaders": [
"*"
],
"AllowedMethods": [
"GET",
"PUT",
"POST",
"HEAD"
],
"AllowedOrigins": [
"http://my.domain.com" // Change to your domain
],
"ExposeHeaders": [
"ETag"
],
"MaxAgeSeconds": 3600
}
]
```
### GCP GCS
GCS Access can be managed using Workload Identity.
#### Workload Identity
The values config for external buckets:
```yaml theme={null}
global:
buckets:
images: "my-images-bucket"
bucketsConfig:
type: gcs
useWorkloadIdentity: true
artefactsBucketConfig:
type: gcs
bucketName: my-artefacts-bucket
useWorkloadIdentity: true
```
The service accounts using the role need to be annotated using the following values:
```yaml theme={null}
server:
serviceAccount:
annotations:
iam.gke.io/gcp-service-account: my-service-account
vulnerability-database:
serviceAccount:
annotations:
iam.gke.io/gcp-service-account: my-service-account
```
### Permissions and CORS
The Service Account used to access the buckets needs the following permissions:
* Storage Object Creator
* Storage Object User
* Storage Object Viewer
A CORS policy must be set on the Images bucket as the application will present self-signed URLs to the user. See the following document for how to set up CORS on GCS: [https://cloud.google.com/storage/docs/using-cors](https://cloud.google.com/storage/docs/using-cors)
This policy should allow the necessary origins and methods for the application to function correctly:
```json theme={null}
[
{
"origin": ["http://my.domain.com"], // Change to your domain
"method": ["GET", "PUT", "POST", "HEAD"],
"responseHeader": ["ETag"],
"maxAgeSeconds": 3600
}
]
```
## Third-Party Charts
The Binarly Installation comes with a set of third-party charts that are used to support the platform. The installation of these charts is automated by default for ease, but ideally these components should be installed and managed outside of the Binarly installation and disabled in the BTP chart values.
### Argo Workflows (Required)
[Argo Workflows](https://argoproj.github.io/argo-workflows/) is an open-source container-native workflow engine for Kubernetes. It allows you to define and manage complex workflows using a simple YAML syntax. The Binarly application can leverage Argo Workflows for advanced orchestration and automation tasks.
If this is managed outside of the BTP application, please ensure that the following are set in the values file:
```yaml theme={null}
"argo-workflows":
enabled: false
```
### Secretsgen Controller (Semi-Optional)
[Secretgen Controller](https://github.com/carvel-dev/secretgen-controller) generates secrets from a template. This is used to generate the secrets required for the Binarly application.
This can be disabled if the secrets are managed outside the BTP application, or installed separately. To install separately, you can use the chart from `charts/secretgen-controller` in the BTP chart, and adjust the values to disable the bundled deployment:
```yaml theme={null}
"secretsgen-controller":
enabled: false
```
### Keycloak (Required)
[Keycloak](https://www.keycloak.org/) is an open-source identity and access management solution. This is used to manage the authentication for the Binarly application.
If installing this manually, please ensure that the following are set in the values file:
```yaml theme={null}
"keycloak":
enabled: false
```
Additionally, please set up a secret in the BTP namespace called `keycloak` with the following keys:
```yaml theme={null}
admin-password: (The password for the Keycloak admin user)
```
and pass the correct configuration to the BTP chart:
```yaml theme={null}
keycloak:
adminUser: (The username for the password in the secret)
server:
keycloak:
internalHost: keycloak.my.domain.com (The internal host for Keycloak)
```
### Zalando Postgres Operator (Optional)
[Zalando Postgres Operator](https://postgres-operator.readthedocs.io/en/latest/) is a Kubernetes operator for managing PostgreSQL clusters. This is used to manage the PostgreSQL databases required for the Binarly application if required.
If installing this manually, please ensure that the following are set in the values file:
```yaml theme={null}
"postgres-operator":
enabled: false
```
In addition to this, the operator requires network access to the PostgreSQL instances. If you are using the built-in BTP network policy please ensure the operator namespace is whitelisted.
### MinIO Operator (Optional)
[MinIO-Operator](https://min.io/docs/minio/kubernetes/upstream/operations/installation.html) is a Kubernetes operator for managing MinIO clusters that mimic AWS S3 object storage. This is used to manage the MinIO cluster if required.
If installing this manually, please ensure that the following are set in the values file:
```yaml theme={null}
"operator":
enabled: false
```
# Installation
Source: https://docs.binarly.io/on-prem/v3/installation
# Overview
This repository contains the installer for Binarly On-Prem. The installer uses Helmfile and various Helm charts to set up all necessary components.
# Prerequisites
* Access to a Kubernetes cluster (at least with version `1.29.0` or newer).
* `kubectl` configured to interact with your cluster.
* `helm` installed, if using Helm for deployment. `v3.17.0` or newer is required.
* A Linux, macOS, or Windows with WSL enabled.
* Access credentials for Binarly's Artifact Registry (provided with the installer).
* Secrets and values set up as described on the [Configuration](./configuration) page.
The [Considerations](./considerations.mdx) page contains information pertinent to the install and should be read fully before proceeding
## Deployment
### Helm
1. Set up Secrets as described in the [Configuration/Binarly Secrets](./configuration#binarly-secrets) section.
2. Create a `values-overlay.yaml` file with the necessary configuration. This is detailed in the [Configuration/Values](./configuration#values) section.
3. Read the [Third Party Charts](./considerations#third-party-charts) section and ensure any required third-party components are installed.
CRD management in Helm leaves a lot to be desired, and some CRDs may not be installed properly, at an older version, or not at all. If you encounter issues, the CRDs can be applied one by one using `kubectl`, or a `helm install` of the individual charts.
To deploy the Binarly Transparency Platform, use the following command to create the CRDs:
```bash theme={null}
helm template binarly-transparency-platform \
oci:///charts/binarly-transparency-platform: \
-f values-overlay.yaml | \
yq e 'select(.kind == "CustomResourceDefinition")' - | kubectl apply -f -
```
then deploy the application:
```bash theme={null}
helm upgrade --install binarly-transparency-platform \
oci:///charts/binarly-transparency-platform: \
-f values-overlay.yaml --namespace {Your Namespace} \
--skip-crds \
--take-ownership \
--timeout 15m \
--create-namespace
```
### ArgoCD
If you are using ArgoCD, you can create an Application manifest to deploy this chart. Here is an example, with sample values:
```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: binarly-transparency-platform
namespace: argocd
spec:
project: default
source:
helm:
values: |
global:
argoCD: true # Important to disable helm-specific hooks
storageClassName: standard
ingressClassName: tailscale
basedomain: binarly.io
dashboard:
hostname: "dashboard"
keycloak:
hostname: "keycloak"
bucketsConfig:
publicEndpoint: https://minio-api.binarly.io # The public endpoint for MinIO, if using the built-in data storage option
keycloak:
ingress:
hostname: "keycloak.binarly.io" # Unfortunately this has to be set twice
scan-workflow: # Specific configuration for the scanner jobs
workflow:
storageClassName: "premium"
nodeSelector:
workload: tools
tolerations:
- effect: NoSchedule
key: workload
operator: Equal
value: tools
repoURL: {The Repository URL}
targetRevision: {The required version}
chart: binarly-transparency-platform
destination:
server: https://kubernetes.default.svc
namespace: binarly-transparency-platform
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- ServerSideApply=true
- RespectIgnoreDifferences=true
- CreateNamespace=true
ignoreDifferences:
- jsonPointers:
- /data/password
- /data/admin-password
kind: Secret
```
### FluxCD
If you are using FluxCD, you can create a HelmRelease manifest to deploy this chart. Here is an example with sample values:
```yaml theme={null}
# -- More information on HelmRepository and HelmRelease can be found at https://fluxcd.io/flux/components/helm/helmreleases/
apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
name: binarly-transparency-platform
namespace: binarly-transparency-platform
spec:
type: "oci"
url: {The Repository URL}
interval: 10m
secretRef:
name: binarly-registry
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
name: binarly-transparency-platform
namespace: binarly-transparency-platform
spec:
interval: 5m
chart:
spec:
chart: binarly-transparency-platform
version: {The required version}
sourceRef:
kind: HelmRepository
name: binarly-transparency-platform
namespace: binarly-transparency-platform
values:
global:
registryHost: "registry.binarly.io"
storageClassName: standard
ingressClassName: tailscale
basedomain: binarly.io
dashboard:
hostname: "dashboard"
keycloak:
hostname: "keycloak"
bucketsConfig:
publicEndpoint: https://minio-api.binarly.io # The public endpoint for MinIO, if using the built-in data storage option
keycloak:
ingress:
hostname: "keycloak.binarly.io" # Unfortunately this has to be set twice
scan-workflow: # Specific configuration for the scanner jobs
workflow:
storageClassName: "premium"
nodeSelector:
workload: tools
tolerations:
- effect: NoSchedule
key: workload
operator: Equal
value: tools
install:
createNamespace: true
upgrade:
remediation:
retries: 3
```
## Post-Deployment
### User Setup
After installation is complete, a user needs to be set up on Keycloak before accessing the platform. To do this, follow these steps:
1. Access the Keycloak Admin Console at the configured keycloak hostname (e.g., `https://keycloak.binarly.cloud`).
2. Get the admin password using the following command:
```bash theme={null}
kubectl get secret -n {{ The installation namespace }} keycloak -o jsonpath='{.data.admin-password}' | base64 --decode
```
3. Log in to the Keycloak Admin Console using the username `admin` and the password obtained in the previous step.
4. Click "Manage Realm", then "BinarlyRealm".
![Manage Realm]()
![BinarlyRealm]()
5. Click "Users" in the left sidebar, then click "Add User".
6. Fill in the user's email and add `org_admin` in the Binarly Role field, and save.
![New User]()
7. Navigate to the "Credentials" tab and set a password for the user.
![Create Credentials]()
![Set Credentials]()
8. Log in to the Binarly Transparency Platform at the configured dashboard hostname (e.g., `https://dashboard.binarly.cloud`) using the email and password set in the previous step.
Please do not remove the `binarly-admin` user. This user is used by the application for user management and cannot be used to access the platform.
### Running a Scan
After logging in, you can refer to the [user guides](../../user-guides/get-started/first-scan.mdx) for how to use the platform.
# Uninstallation
Source: https://docs.binarly.io/on-prem/v3/uninstallation
To uninstall the Binarly Transparency Platform, you can use Helm or ArgoCD, depending on how you initially deployed the platform.
## Helm
If you used Helm to install the platform, you can uninstall it with the following command:
```bash theme={null}
helm uninstall binarly-transparency-platform --namespace binarly-transparency-platform
```
This command will remove the application and all its resources from the specified namespace.
## ArgoCD
If you used ArgoCD to deploy the platform, you can uninstall it with the following command:
```bash theme={null}
argocd app delete binarly-transparency-platform
```
This command will remove the application and all its resources from the specified namespace.
## FluxCD
If you used FluxCD to deploy the platform, you can uninstall it by deleting the HelmRelease resource:
```bash theme={null}
kubectl delete helmrelease binarly-transparency-platform --namespace binarly-transparency-platform
```
This command will remove the HelmRelease and all associated resources from the specified namespace.
# Virtual Machine Deployment
Source: https://docs.binarly.io/on-prem/v3/virtualmachine
The Binarly Transparency Platform can be deployed using a pre-configured virtual machine based on Talos Linux and Kubernetes.
Using this installation method is **not recommend**, it is also:
* Less stable
* Does not scale up and down
* Less observable
This method is only for short proof-of-concept or very low traffic scenarios. Depending on the machine size, scan times can be greatly impacted.
Whilst Talos Linux capable for clustering (worker.yaml), our VM designed and supported as a standalone installation. Customers are welcome to [scale horizontally](#scaling-horizontally) at their own discretion.
# Requirements
* A machine with at least 32 cores and 128GB of RAM
* A root disk of at least 100GB
* A data disk of at least 300GB
* A reverse proxy at front of this machine
* reverse proxy is to forward HTTP (80) traffic to HTTP (30080) and HTTPS (443) traffic to HTTPS (30443) on the VM
# Setup
Setup will depend on your hypervisor of choice, this Virtual Machine has been tested using:
* Kubevirt
* Proxmox
## Disks
* The provided disk.img should be used as the root volume, and may need to be converted using qemu-img
* The data disk should be attached to `/dev/vdb` and be blank. This disk should be detached between upgrades and reattached as it contains all application data
## Ports
* 50000 and 50001 for access to the talos API
* 6443 for access to the Kubernetes API
* 30080 and 30443 for application access
### Scaling horizontally
There are a few additional requirments when it comes to scaling horizontally.
1. VMs must have network access between each other
* The common Kubernetes ports must be unrestricted as described in [the official Kuberntes doc](https://kubernetes.io/docs/reference/networking/ports-and-protocols/)
* The port (TCP) 50000 on Talos workers to communicate with the controlplane
* The port (UDP) 8285 and 8472 must be open for Flannel's (VXLAN) on all nodes
2. When corporate firewall/proxy is in place, the UDP checksum field on the VXLAN packets **can** be corrupted. In that case, try deploying the following to avoid corrupted checksum.
```yaml theme={null}
apiVersion: apps/v1
kind: DaemonSet
metadata:
name: fix-vxlan-csum
namespace: kube-system
labels:
app: fix-vxlan-csum
spec:
selector:
matchLabels:
app: fix-vxlan-csum
template:
metadata:
labels:
app: fix-vxlan-csum
spec:
hostNetwork: true
tolerations:
- operator: Exists
containers:
- name: fix
image: docker.io/nicolaka/netshoot@sha256:b09d9b21381f47a79b3cbcb30da25266dc17186ea00ae65e99fdc51396f48e70 #v0.16
securityContext:
privileged: true
command:
- sh
- -c
- |
set -x
for i in $(seq 1 60); do
[ -d /sys/class/net/flannel.1 ] && break
sleep 5
done
ethtool -K flannel.1 tx-checksum-ip-generic off || true
ethtool -k flannel.1 | grep tx-checksum-ip-generic
sleep infinity
resources:
requests:
cpu: 10m
memory: 32Mi
limits:
memory: 64Mi
```
## Example
During testing these VMs are deployed on Kubernetes via [Kubevirt](https://kubevirt.io/) with the following configuration:
```yaml theme={null}
apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
name: talos-node
labels:
kubevirt.io/domain: talos-node
spec:
runStrategy: Always
template:
spec:
networks:
- name: defaultnetwork
pod: {}
tolerations:
- key: dedicated
operator: Equal
value: kubevirt
effect: NoSchedule
domain:
cpu:
cores: 32
resources:
requests:
memory: 128Gi
limits:
memory: 256Gi
devices:
interfaces:
- name: defaultnetwork
masquerade: {}
ports:
- port: 30080
- port: 30443
- port: 32000
- port: 50000
- port: 6443
disks:
- name: rootdisk
disk: { bus: virtio }
- name: secondarydisk
disk: { bus: virtio }
volumes:
- name: rootdisk
dataVolume:
name: talos-boot-dv
- name: secondarydisk
persistentVolumeClaim:
claimName: talos-data-pvc
```
## Configuring BTP
As part of the installation package there are 4 more files that provide access to the VM:
* talosconfig
* kubeconfig
* controlplane.yaml
* worker.yaml
* btp.yaml
These files should be treated as *confidential*. They contain the certificates that allow access to the machine and without them the machine cannot be changed. They are specific to the VM instance they were distributed with.
Configuration of the application requires interacting with the machine using talosctl to update parameters. This can be done either from a machine with network access to the VM or from a Kubernetes pod running inside the VM.
### Configuring the BTP App
The `btp.yaml` file contains the configuration for your deployment and will need to be updated. This can be done by adding values (more information in the [configuring BTP](#configuring-btp) section) to the yaml file and applying it to the cluster.
As an example the domain will need to change to match your internal domain:
```yaml highlight={14} theme={null}
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: binarly-transparency-platform
namespace: argocd
spec:
project: default
source:
helm:
values: |
# These values are provided by us and shouldn't be changed, except `basedomain`
global:
...
basedomain: dev.binarly.cloud # Change this value to your desired basedomain.
...
```
#### Domains
BTP comes with a set list of subdomains that will be accessible through the basedomain. These domains are the following:
* dashboard.basedomain
* kc.basedomain
* minio-api.basedomain
> Please make sure these domain names are set in your DNS server and the value set to the IP of your reverse proxy.
### Machine with Network Access
Talos uses mutual transport layer security to ensure it can only be accessed on a strict list of domains. The domains are listed in the `controlplane.yaml` file, in these examples `talos-node.local` is used.
Steps:
1. Add `talos-node.local` DNS entry for the VM (Or add an entry for `talos-node.local` in /etc/hosts)
2. Install:
1. [talosctl](https://docs.siderolabs.com/omni/getting-started/how-to-install-talosctl)
2. [kubectl](https://kubernetes.io/docs/tasks/tools/)
3. Make changes to the btp.yaml file to suit your needs
4. Apply those changes with:
```bash theme={null}
export TALOSCONFIG=/path/to/talosconfig
talosctl config endpoint talos-node.local
talosctl config node talos-node.local
talosctl kubeconfig
kubectl apply -f btp.yaml
```
### Kubernetes Pod
The local address (127.0.0.1) is valid to reconfigure the VM and all Kubernetes calls originate from there.
Steps:
1. Get access to the cluster
```bash theme={null}
export TALOSCONFIG=/path/to/talosconfig
talosctl kubeconfig
```
2. Create a pod on the Kubernetes cluster:
```bash theme={null}
kubectl run talos-config \
--image=alpine \
--restart=Never \
-- sleep infinity
```
3. Wait for the pod to be ready:
```bash theme={null}
kubectl wait --for=condition=Ready pod/talos-config
```
4. Make changes to the `btp.yaml` file to suit your needs
5. Copy the `talosconfig` and `btp.yaml` files to the pod:
```bash theme={null}
kubectl cp /path/to/talosconfig default/talos-config:/talosconfig
kubectl cp /path/to/btp.yaml default/talos-config:/btp.yaml
```
6. Install `talosctl` and `kubectl`, then apply the changes:
```bash theme={null}
kubectl --kubeconfig /path/to/kubeconfig exec -it talos-config -- sh -c \
'apk add --no-cache jq curl && \
curl -sL https://github.com/siderolabs/talos/releases/latest/download/talosctl-linux-amd64 \
-o /usr/local/bin/talosctl && \
chmod +x /usr/local/bin/talosctl
apk add kubectl
export TALOSCONFIG=/path/to/talosconfig
talosctl config endpoint 127.0.0.1
talosctl config node 127.0.0.1
talosctl kubeconfig
kubectl apply -f btp.yaml
```
7. Once complete, delete the pod:
```bash theme={null}
kubectl delete pod talos-config
```
## Routing to the Virtual Machine
The Virtual Machine can be routed to either with a load balancer that terminates TLS and forwards plaintext traffic, or TLS can be terminated by the virtual machine's internal load balancer.
### External Load Balancer
You must set up a load balancer with certificates for your domain, terminating TLS at the load balancer level and forwarding traffic to the application access ports on the load balancer.
The load balancer should be configured with a DNS record for your domain, and the domain should be passed to the Binarly platform (more information in the [configuring BTP](#configuring-btp) section).
### Using the Internal Load Balancer
The virtual machine employs a [Kubernetes Gateway](https://kubernetes.io/docs/concepts/services-networking/gateway/) listening on the application ports and can be used as a traffic entrypoint. This requires some configuration of the Gateway in Kubernetes to set up the certificate and TLS termination.
Due to restricted ports when using this ingress method you will need to access the VM using the port as part of the domain. For example: `https://binarly-dashboard.internal:30443` or `http://binarly-dashboard.internal:30080`.
### Setting up Internal Certificates
Once there is a domain pointing to the virtual machine's IP address, apply certificates to the gateway:
1. Get access to the kubernetes cluster following the instructions from the [Machine with Network Access](#machine-with-network-access) section
2. Create a secret containing your certificate in the `default` namespace by editing this template:
```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
name: gateway-cert
namespace: default
type: kubernetes.io/tls
data:
tls.crt:
tls.key:
```
3. Deploy the secret to the cluster by the following command.
`kubectl apply -f .yaml`
4. Run `kubectl edit Gateway ingress-gateway -n default` which will open the Gateway in a local editor
5. Replace the `https` listener entry (Whole file provided for an example):
```yaml theme={null}
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: ingress-gateway
spec:
gatewayClassName: istio
infrastructure:
parametersRef:
group: ""
kind: ConfigMap
name: ingress-gateway-config
listeners:
- name: http
protocol: HTTP
port: 80
allowedRoutes:
namespaces:
from: All
# This section below needs to be changed
- name: https
protocol: HTTPS
port: 443
allowedRoutes:
namespaces:
from: All
hostname: "" #must be quoted
tls:
certificateRefs:
- group: ""
kind: Secret
name: gateway-cert
mode: Terminate
```
# Release cadence & versioning
Source: https://docs.binarly.io/release-notes/release-cadence
How Binarly versions and ships the Transparency Platform.
Starting with 3.8.1, the Binarly Transparency Platform ships on a **weekly release cadence**.
## Version format
Releases use semantic versioning with a date-based build metadata suffix:
```
MAJOR.MINOR.PATCH+YYYY.MM.DD
```
| Segment | Meaning |
| ------------ | ---------------------------------- |
| `MAJOR` | Incompatible API or schema changes |
| `MINOR` | New features, backwards-compatible |
| `PATCH` | Bug fixes and minor improvements |
| `YYYY.MM.DD` | Release date |
The version displayed in the Binarly Transparency Platform UI matches this identifier exactly, so you can correlate what you see in the product with the corresponding release notes entry.
## Release schedule
Releases ship weekly. Each release may include platform features, analysis engine updates, vulnerability database refreshes, and rule detection improvements — all documented in the corresponding release notes page.
On-prem customers: your deployment version is shown in the platform UI. Match it against the release notes by the `MAJOR.MINOR.PATCH` segment.
# v2.0
Source: https://docs.binarly.io/release-notes/v2.0
[Release Blogpost](https://www.binarly.io/blog/introducing-binarly-transparency-platform-v2-0)
*This release brings enhanced clarity and transparency to the software supply chain ecosystem through the lens of Binary Risk Intelligence. It enables enterprise security teams and empowers product security organizations to implement a secure-by-design approach at scale.*
## Features
* Ensure post-build compliance by continuously monitoring and validating for security-related changes.
* Gain insights into the security posture of IoT and XIoT devices, enabling a deeper understanding of their vulnerabilities and dependencies.
* Identify malicious behavior and hidden backdoors within binaries based on their behavior.
* Detect insecure coding practices and coverage of build-time mitigations within each binary.
* Gain insights into what software is truly made of, enabling production and validation of SBOMs for a deeper understanding of corresponding risks.
* Detect license obligations buried within the binaries you depend on to avoid legal issues down the road.
* Detect embedded keys, if they are being used, and insecure cryptographic usage patterns to help catch key leaks and correct cryptographic usage before shipping.
* Empower security leadership to make informed decisions with a curated dashboard.
# v2.5
Source: https://docs.binarly.io/release-notes/v2.5
[Release Blogpost](https://www.binarly.io/blog/introducing-binary-reachability-analysis-binarly-transparency-platform-v2-5)
*Binarly Transparency Platform v2.5 adds Binary Reachability Analysis to prioritize reachable vulnerable code (no source), plus custom rules, expanded hardening checks, richer crypto/CBOM for PQ planning, and improved secrets & Docker risk scanning.*
## Features
* Binary Reachability Analysis ([U.S. Patent 12,287,885](https://patents.google.com/patent/US12287885)): prioritizes findings by whether vulnerable code is actually reachable in compiled binaries, with direct/exported/referenced/undetermined levels.
* Custom semantic detection rules: define org-specific rules (incl. non-CVE issues) with reachability baked in and pseudo-code evidence.
* Expanded “Weak Binaries” hardening checks: more mitigation tests across code, executables, and the Linux kernel; flags risky C/C++ usage (e.g., CWE-477/676).
* Enhanced cryptographic discovery & CBOM: deeper detection of crypto assets/algorithms to support post-quantum migration planning.
* Secrets discovery & better Docker container risk detection: finds exposed items like OAuth credentials, JWTs, encryption keys, and API tokens.
# v2.7
Source: https://docs.binarly.io/release-notes/v2.7
[Release Blogpost](https://www.binarly.io/blog/binarly-transparency-platform-v2-7-propels-enterprises-toward-post-quantum-readiness)
*We are proud to announce a new release which brings significant enhancements to the Binary Transparency Platform. Introducing new features, performance upgrades, and critical updates to better support software supply chain transparency, vulnerability remediation, and regulatory compliance.*
## Hero Features
* **Post-quantum cryptography compliance** - Understand which cryptographic algorithms in use comply with NIST guidance on post-quantum readiness (i.e. NIST IR 8547) and see what changes are needed for non-compliant algorithms.
* **Cryptographic Reachability** - Prioritize actionable findings by seeing which cryptographic algorithms in a binary are reachable (actively used).
## Features
* **Vendor signed ELF binaries** - Detect signed Linux ELF binaries and see their cryptographic details.
* **Unsafe functions** - See any insecure C/C++ library functions used in binaries and get suggestions on safer alternatives that align with Secure by Design principles.
* **Known fixes** - Find out which dependency vulnerabilities have fixes available and see the fix details.
* **Secure by Design** - Detect software development practices that aren’t aligned with CISA’s Secure by Design principles and the NIST SP 800-218 Secure Software Development Framework (SSDF).
* **Better grid controls** - A new filter drawer and more column options that give more flexibility and control over how you filter, sort and search within the Findings grid, making it easier to get the view you want.
* **Enhanced reports** - New Image and Finding reports with more details, that are easier to read, and the ability to generate customized reports based on filters.
## Binarly Analysis Engine
* **Next-generation binary scanner** - We rewrote the core of our scanner making scans 2.5x faster on average, and introduced parallel scanning to enable even bigger boosts to scanning across Docker containers, ISO images, and firmware.
* **Linux kernel hardening** - Detection of Linux kernel hardening and recommendations.
* **Complex vulnerability support** - Detection and aggregation of complex vulnerabilities that span multiple binaries for a more comprehensive view of risks.
* **UEFI hardening** - More robust detection of UEFI mitigations under different build configurations (handling of function inlining, outlining, etc.) including improved checks for Stack Guard and stack canaries.
* **Bootkitty UEFI Malware** - Added detection for Bootkitty Linux bootloader.
# v2.8
Source: https://docs.binarly.io/release-notes/v2.8
*Advanced Image Diffing, RBAC, Enhanced Vulnerability Detection. The March release of the Binarly Transparency Platform simplifies your management and validation workflows, while expanding the types of things you can see and act on.*
## Hero Features
* **Image version comparison** - Quickly and easily understand what has been added, removed unchanged between scanned binaries.
* **Cryptographic protocols** - Gain visibility into the presence and versions of cryptographic protocols contained within compiled binaries.
## Features
* **Role-based access control (RBAC) improvements** - Manage user creation and granularly control access to sensitive images findings and functions within the platform.
* **View and download keys and certificates** - Get the details for any keys or certificates (vulnerable and non-vulnerable) in an image and download them.
* **Per-version findings** - See which other versions of an image contain the same finding and see the historical view of that finding in older images.
## Binarly Analysis Engine
* **Cryptographic Material** - Improved self-signed certificate detection.
* **Unknown Vulnerabilities** - Enhanced detection of SMM arbitrary code execution vulnerabilities (CWE-749, CWE-829) in UEFI-based firmware.
* **Secrets** - Increased accuracy and enhanced scanning capabilities.
* **Known Vulnerabilities** - Redesigned microcode detection for Intel and AMD devices (see Binarly tracking updates for CVE-2024-56161).
* **Code Analysis** - Enhancements in pseudocode and decompilation processes to strengthen code analysis capabilities.
* **Mitigations** - Updated guidance from the Linux Kernel Self-Protection Project (KSPP).
# v3.0
Source: https://docs.binarly.io/release-notes/v3.0
[Release Blogpost](https://www.binarly.io/blog/binarly-transparency-platform-v3-0-actionable-threat-intelligence-meets-exploitation-aware-prioritization)
*We are proud to announce the availability of Binarly Transparency Platform v3.0, with real‑time Threat Intelligence Monitoring fused with an evidence-based Exploit Maturity Scoring (EMS) system. The latest release of the Binarly Transparency Platform introduces powerful new capabilities that bring clarity to the chaos of vulnerability management and software supply chain security.*
## Hero Features
* **Important Findings** - Immediately see the findings with elevated risk that we believe should be actioned immediately or create your own priority views that you can quickly jump back into.
* **Exploitation Maturity Scoring** - EMS leverages real-time exploitation signals to provide a weighted linear scoring approach. Developed completely in-house, the EMS is designed not to predict the future, but to measure the present by using real-world signal. You can learn more about the EMS [here](https://www.binarly.io/blog/the-hidden-danger-of-probabilistic-scoring-introducing-exploitation-maturity-score-ems).
* **Threat Intelligence Monitoring** - Threat intelligence monitoring leverages feeds from our internal vulnerability database as well as external sources such as NVD, EPSS, and CISA. It combines these threat feeds with other information, including our own Exploitation Maturity Scoring EMS, to surface high-risk findings. By tracking escalations and trends, the system provides real-time visibility into evolving and emerging threats within the binaries assessed and managed through the Platform.
## Features
* **Global Search** - Explore the power of refined search capabilities to uncover detailed information about sophisticated threats like CosmicStrand or a specific CVE for example. Navigate seamlessly through intuitive interfaces to access critical findings and enhance your cybersecurity strategy. Get the details for any keys or certificates (vulnerable and non-vulnerable) in an image and download them.
* **Auto-Advisories and VEX** - When you discover a new unknown vulnerability with the Binarly platform, automatically generate an actionable advisory that can be shared with your vendor. For known vulnerabilities, create VEX files to communicate them across your supply chain.
* **Reporting updates: PQC Compliance and CSV export** - Save any grid view in CSV format so you can share it and load it into your favorite spreadsheet program for further analysis. Also, new Post-Quantum Compliance Reports are now available to map to NIST IR 8547 and provide visibility into Post-Quantum supply chain resilience.
## Binarly Analysis Engine
* **Added compiler information** - Extended detection of compilers.
* **Cryptographic Materials** - Enhanced cryptographic artifact extraction.
* **Unknown Vulnerabilities** - Expanded capabilities to detect new classes of vulnerabilities including improper input validation, import handling, abnormal PE parsing, and microcode issues in UEFI-based firmware.
* **Secrets** - Increased accuracy and enhanced scanning capabilities.
* **Code Analysis** - Enhancements in pseudocode and decompilation processes to strengthen code analysis capabilities.
# 3.11.3+2026.04.07
Source: https://docs.binarly.io/release-notes/v3.11.3
Binarly v3.11.3 release notes: large-scale scan stability, expanded secrets scanning file types and validators, and an SBOM version reporting fix.
## Features
### Platform
* **Smarter scan retry behavior**: The platform now retries only on out-of-memory failures, not on other error types. This reduces wasted time on large images where a retry would fail for the same reason.
### Secrets
* **Expanded file type coverage**: Secrets scanning now covers Go source files, Markdown files, and SQL sources.
* **Additional token validators**: Secrets scanning can now validate tokens from additional third-party services.
## Binarly Analysis Engine
* **Analysis Framework Enhancements**
* Improved memory management during firmware unpacking, reducing out-of-memory failures on large images.
## Bug Fixes
* **SBOMs now report the correct BTP version**: Generated SBOMs previously reported an incorrect platform version; this is now fixed.
* **Email notification template**: Corrected formatting issues in the email notification template.
* **Healthcheck results in application logs**: Healthcheck outcomes are now written to the application log, improving observability for on-prem deployments.
* **Server version in logs**: The platform version is now recorded in logs at startup, making it easier to correlate behavior with deployment history.
# 3.19.2+2026.04.15
Source: https://docs.binarly.io/release-notes/v3.19.2
Binarly v3.19.2 release notes: finding variants in SBOM, VEX, and CBOM exports, VulHunt detection for CVE-2024-56171 in libxml2, and reliability fixes.
## Features
### Compliance
* **Variants in SBOM, VEX, and CBOM exports**: Finding variants configured per product are now respected when generating compliance reports. Exported reports reflect the same variant-derived attributes shown in the UI.
## Binarly Analysis Engine
* **New Context-Aware Rule Detection (VulHunt, FwHunt, YARA)**
* Added VulHunt detection for CVE-2024-56171 in libxml2.
## Bug Fixes
* **Finding instance list truncation**: The finding instance list was silently capped at 50 entries. All instances are now returned correctly.
* **JSON download for large finding sets**: Downloading the detailed JSON report failed when a scan had more than 20,000 findings. This is now fixed.
* **Multiple annotations on matching ranges**: Findings with multiple annotations and no explicit range boundary now display all annotations correctly.
# 3.22.0+2026.04.21
Source: https://docs.binarly.io/release-notes/v3.22.0
Binarly v3.22.0 release notes: a default comparison column, plus general availability of CVSS vector display, triage improvements, and findings scope filtering.
## Features
### Comparison
* **Default comparison column**: The comparison view now opens with the Found/Not Found column selected by default, showing differences immediately rather than all findings.
### General availability
* **CVSS vector breakdown**: Individual CVSS vector metric values (Attack Vector, Attack Complexity, Privileges Required, etc.) are now displayed by default in finding details for all users.
* **Triage improvements**: The updated triage workflow is now the default experience for all users.
* **Findings scope filter**: Scope-based filtering in the findings view is now available to all users.
# 3.25.2+2026.04.28
Source: https://docs.binarly.io/release-notes/v3.25.2
Binarly v3.25.2 release notes: CycloneDX SBOM output fix, restored Components tab hierarchy, and more reliable vulnerability database queries.
## Binarly Analysis Engine
* **Vulnerability Database Service**
* Added retry logic and configurable timeouts for vulnerability database queries, improving scan reliability under transient network conditions.
## Bug Fixes
### Compliance
* **CycloneDX root component hashes and version**: The root component in CycloneDX SBOM exports now includes file hashes and the version field as required by the specification.
### Platform
* **Component hierarchy in the Components tab**: Component relationships were incorrectly flattened in the Components tab view. The correct hierarchy is now preserved.
# 3.31.1+2026.05.06
Source: https://docs.binarly.io/release-notes/v3.31.1
Binarly v3.31.1 release notes: redesigned findings page by default, SSVC column reorder, improved SSVC scoring, and VulHunt detection for CVE-2024-25178.
## Features
### Findings
* **Redesigned findings page**: The updated findings page is now the standard experience for all users.
* **SSVC column reorder**: SSVC decision columns now appear after Reachability in the findings grid, matching the standard SSVC decision model ordering. The SSVC column is hidden on finding tabs where it does not apply, including cryptographic materials, secrets, and weaknesses.
## Binarly Analysis Engine
* **Vulnerability Database Service**
* SSVC decisions are now computed server-side for all findings.
* Secondary CVSS metrics are now sourced from the CVE Project list, improving scoring accuracy.
* Removed grsecurity as an advisory source.
* Fixed an issue where oversized variant descriptions caused scan failures for certain linux kernel vulnerability entries.
* **New Context-Aware Rule Detection (VulHunt, FwHunt, YARA)**
* Added VulHunt detection for CVE-2024-25178 in libluajit.
* **Analysis Framework Enhancements**
* Firmware unpacking performance improvements.
* Fixed a potential regression in UEFI firmware unpacking.
* Secret validity checks now include retry logic and configurable timeouts when contacting validation services, reducing failed validity lookups under load.
## Bug Fixes
### Reports
* **Advisory report generation**: Fixed an error that prevented advisory reports from being generated for certain findings.
# 3.35.1+2026.05.13
Source: https://docs.binarly.io/release-notes/v3.35.1
Binarly v3.35.1 release notes: secret validity in the findings grid, standalone UEFI MM module analysis, U-Boot image support, and CVE-2026-33243 detection.
## Features
### Secrets
* **Secret validity in the findings grid**: Secret findings now include a Validity column showing whether each detected secret is confirmed active (`Valid`), confirmed inactive (`Invalid`), or could not be checked (`Undetermined`).
### Findings
* **Active filter visual indicator**: Columns with an active filter now display a visual indicator in the grid header, making it immediately clear which columns are currently filtered.
### Performance
* **Faster scan completion**: Vulnerability database lookups during scan finalization are now executed outside the database transaction. This reduces contention when many findings require VDB lookups, cutting overall scan completion time.
## Binarly Analysis Engine
* **New Platforms/Formats**
* VulHunt can now detect vulnerabilities in U-Boot binaries.
* Added support for extracting and analyzing U-Boot firmware images.
* **New Context-Aware Rule Detection (VulHunt, FwHunt, YARA)**
* Added VulHunt detection for CVE-2026-33243 in U-Boot.
* **Analysis Framework Enhancements**
* Added analysis of standalone Management Mode (MM) UEFI modules.
* Extended the UEFI knowledge base with 500+ additional GUIDs and updated type libraries for NVIDIA firmware.
* Improved external function call recovery for x86 PIE ELF binaries.
## Bug Fixes
### Analysis Engine
* **Cryptographic material processing**: Fixed a potential panic when analyzing EC keys that lack a generator point.
* **Execution environment setup**: Fixed an issue in the analysis execution environment that could cause scan failures in certain configurations.
* **Missing firmware components in scan results**: Fixed an issue where components referenced only through archive directory entries were excluded from analysis, causing some firmware contents to not appear in scan results.
### Cryptographic materials
* **Bulk download in the cryptographic assets grid**: Selecting multiple assets and triggering bulk download now works correctly. Previously the action completed without downloading anything.
### Findings
* **Default issue status filter when navigating from the sidebar**: Opening the findings page via the sidebar now applies the default issue status filter (New and In Progress), consistent with navigating directly to the page.
* **Database search triggers**: Disabled database search triggers and the search UI to resolve lock contention issues during scan finalization.
### Compare
* **Swap Compare button**: Pressing Swap Compare now correctly re-fetches the grid and updates the comparison filter. Previously the swap had no visible effect until manually triggering a reload.
# 3.38.1+2026.05.19
Source: https://docs.binarly.io/release-notes/v3.38.1
Binarly v3.38.1 release notes: secret validity in reports, VulHunt detection for CVE-2022-37434 in zlib and NVIDIA DGX Spark MM modules, and a git processing fix.
## Features
### Secrets
* **Secret validity in reports**: Exported reports now include the validity status for each secret finding: `Valid`, `Invalid`, or `Undetermined`.
* **Secret validity in the Important Findings chart**: The Important Findings chart now supports querying by secret validity status.
## Binarly Analysis Engine
* **New Context-Aware Rule Detection (VulHunt, FwHunt, YARA)**
* Added VulHunt detection for CVE-2022-37434 in zlib.
* Added VulHunt detection for vulnerabilities in standalone Management Mode modules in NVIDIA DGX Spark firmware.
* Updated kernel hardening detection rules to align with current KSPP recommendations.
## Bug Fixes
### Analysis Engine
* **Git repository processing regression**: Fixed a regression that caused incorrect behavior when processing firmware images containing git repositories.
# 3.41.0+2026.05.26
Source: https://docs.binarly.io/release-notes/v3.41.0
Binarly v3.41.0 release notes: VulHunt detection for CVE-2026-33243 in U-Boot, extended CVE-2022-37434 zlib coverage, a KSPP ARM hardening check, and CryptoScan key formats.
## Features
* **Additional vulnerability identifier types**: Finding data now includes identifiers from the ALSA, Go, HSEC, PSF, and PYSEC vulnerability databases. Finding properties now include provenance metadata showing which analysis component produced each value.
## Binarly Analysis Engine
* **New Context-Aware Rule Detection (VulHunt, FwHunt, YARA)**
* Added VulHunt detection for CVE-2026-33243 in U-Boot, using string reference analysis instead of binary signatures for more reliable detection across firmware versions.
* Extended VulHunt coverage for CVE-2022-37434 (zlib) to include binaries from versions newer than 1.2.12.
* Updated kernel hardening detection rules to reflect current KSPP recommendations.
* Added a dedicated DEBUG\_WX detection rule for ARM kernels with kernel version specification.
* **Analysis Framework Enhancements**
* CryptoScan can now detect PGP and TSS2 (TPM 2.0) private and public keys, and PKCS#12 private keys.
* CryptoScan now extracts and parses EC keys across all supported private key formats (SSH, PGP, PKCS#12).
## Bug Fixes
### Deployment
* **Duplicate podAntiAffinity in Helm chart**: Fixed an issue where `podAntiAffinity` configuration was declared twice when set in Helm values, causing chart application failures for clusters with this setting configured.
# 3.47.1+2026.06.02
Source: https://docs.binarly.io/release-notes/v3.47.1
Binarly v3.47.1 release notes: secret validity filtering GA, Mitigate detection for Insyde FDM misconfigurations, more finding identifier types, and Python analysis fixes.
## Hero Features
* **Secret validity status**
* Secrets now carry a validity status (valid, invalid, undetermined, or unspecified) that can be used to filter findings. The unspecified status applies to findings that are not secrets. The validity status replaces the previous "Secret | Validated" finding type.
* The finding scope and type filters no longer include the legacy leaked-secret type.
* Existing saved filters that referenced the old secret types are automatically migrated to the new secret type and validity combination.
## Features
* **Finding display names**: Findings now use the first identifier regardless of type when generating the display name. Previously, display names were derived only from BRLY or CVE identifiers, causing incorrect or inflated names for findings with other identifier types.
## Binarly Analysis Engine
* **New Context-Aware Rule Detection (Mitigate)**
* Added detection for Insyde FDM misconfigurations that could allow firmware flash modification. The check identifies unprotected secondary FDM regions and unprotected FvCnvUnCompact sections in Insyde-based UEFI firmware (CWE-354, CVSS 7.6).
## Bug Fixes
### Findings
* **Insyde FDM checker findings**: Insyde FDM misconfiguration findings now display EFI region addresses in hexadecimal. The finding detail view correctly distinguishes the three region types (the misconfigured FDM entry, the FDM store region, and the targeted region), which were previously displayed as a flattened list.
### Analysis Engine
* **Non-deterministic Python package components**: Python package components extracted from firmware are now consistent across scans. Previously, the same firmware image could produce different component sets on separate scans.
* **Python package construction for generic inputs**: Fixed construction of Python package components for firmware unpacked via unblob with generic inputs.
* **CryptoScan: Python packages in tar archives**: Fixed extraction of Python package components packed in tar archives.
* **CryptoScan: Python package format compatibility**: Updated CryptoScan to process the revised python.package component format produced by the firmware normalizer.
# 3.49.1+2026.06.10
Source: https://docs.binarly.io/release-notes/v3.49.1
Binarly v3.49.1 release notes: logarithmic EMS score normalization, VulHunt detection for CVE-2026-45185 in Exim, RSA badkeys CryptoScan checks.
## Binarly Analysis Engine
* **Vulnerability Database Service**
* EMS scores above 8 now use logarithmic normalization, reducing top-tier score saturation from approximately 2,500 findings at EMS 10 down to 13. This provides finer-grained prioritization for high-severity findings. Scores at or below 8 are unchanged.
* **New Context-Aware Rule Detection (VulHunt, CryptoScan)**
* Added VulHunt detection for CVE-2026-45185, a use-after-free vulnerability in Exim affecting versions above 4.97 linked against GnuTLS.
* Added CryptoScan checks for RSA key weaknesses using patterns from the badkeys project, covering small prime factors, small private exponent, polynomial key patterns, key bias, and invalid key parameters.
* **Analysis Framework Enhancements**
* CVEHunt now prioritizes ecosystem package data over NVD. Detections not confirmed by OS package information are filtered out, reducing false positives for Linux distributions with package ecosystem coverage such as Ubuntu.
* Improved CVEHunt project linkage detection with better name-based package matching, reducing misclassification between project and vendored linkage types.
## Bug Fixes
### Analysis
* **Disk image unpacking**: Fixed incomplete unpacking of disk images and archives containing read-only directories.
### Dependencies
* **Duplicate dependency entries**: Fixed a scan failure caused by duplicate dependency entries.
### Vulnerability Data
* **Ubuntu OVAL false positives**: Fixed an issue where vulnerability ranges from Ubuntu OVAL streams were not removed from the database after Ubuntu updated their affected status to unaffected, which caused a small percentage of false positives for Ubuntu ecosystem findings.
# v3.5
Source: https://docs.binarly.io/release-notes/v3.5
*We’re excited to introduce major enhancements to the Binarly platform. The latest Binarly release offers new functionality that converges product security and security research with Custom Rule Management and Threat Hunting with YARA, and native FwHunt support. It also introduces Java archive and bytecode (JVM) analysis and advanced PQC & CBoM inspection for deep visibility into cryptographic materials and reachability across modern software packages.*
## Hero Features
* **[Enterprise-Scale YARA Integration](https://www.binarly.io/blog/evolving-product-security-scaling-yara-detections-with-the-binarly-transparency-platform-v3-5)**
* YARA rules are now part of the Binarly Transparency Platform for enhanced threat hunting and analysis.
* **[Java archive and Java bytecode (JVM) analysis support](https://www.binarly.io/blog/cryptographic-algorithms-identification-in-java-bytecode)** - \[New Ecosystem]
* Dependency Vulnerability detection
* PQC & CBoM: Deep Inspection of Java Cryptographic Materials and Reachability Analysis
* **Custom Rule Manager** - Converged Product Security & Security Research
* Hosted Rule Development Playground
* Custom Rules Threat Hunting scan engine (Playground)
* Integrates with YARA support (in addition to FwHunt rules) for connecting threat intel data feeds
* Ruleset Management System with UAC
* New roles: Rule Admin, Editor and Viewer
* Ruleset context search and navigation
* Ruleset deployment
* Rulesets can be deployed for the entire organization or list of products
* Ruleset API for CI/CD integration
* Tooling can be integrated with any rule management through REST API
## Features
* **Organization Quotas**
* Ease enterprise roll out - Quota can be centrally managed and allocated to teams within the platform.
* Helps to stay in license limits and provides transparency accross teams
* **Triage Enhancements**
* Improved collaboration - Assign issues status, assign to team members, issue comments with markdown support, with dynamically updating charts.
* Per product, across images triage is now possible
* Activity details are recorded with history
* **Enhanced Cryptographic Artifacts extraction** - Detection of UEFI Secure Boot keys and certificates
* **On-prem Deployment Improvements** - Helm chart rework with security and maintainability improvements
## Binarly Analysis Engine
* **New Platforms/Formats**
* Java Archives
* Android Packages
* Lua Bytecode
* OP-TEE kernel
* Portable Executables for Windows
* **Vulnerability Database Service**
* Improved handling of vulnerability data sources
* **New Features**
* Improved unpacking of various UEFI update packages
* Ability to analyze certificates/keys extracted from Secure Boot related variables
* Ability to analyze standalone UEFI modules with PEI/DXE/SMM/Application kinds
* Compiler identification for EFI modules
* Improved processing of source code in order to detect leaked secrets
* Improved processing of Git repositories in order to detect leaked secrets
* Improved support for Linux Kernel extraction and version identification
* Ability to extract ecosystem or ecosystem candidates from arbitrary input files
* Improved identification of ECC (elliptic-curve cryptography) public/private keys
* Structured reporting of ECC keys extracted from certificates and public/private key files
* Identification and reporting of new signature algorithms (SLH-DSA and ML-DSA) extracted from certificates
* CBoM for Java ecosystem
* Identification of cryptographic algorithms in Java Bytecode, including reachability analysis
* Identification of known vulnerabilities in components and dependencies extracted from Java Archives
* YARA engine support (yara-x) with a default rule package containing 170 rules allowing to detect malicious and vulnerable code
* Improved support for [CPE](https://csrc.nist.gov/projects/security-content-automation-protocol/specifications/cpe) and [PURL](https://github.com/package-url/purl-spec)
* **New Detections**
* [BYOVD-style Secure Boot bypass vulnerabilities](https://www.binarly.io/blog/signed-and-dangerous-byovd-attacks-on-secure-boot)
* **New Context-Aware Rule Detection (VulHunt, FwHunt, YARA)**
* FwHunt detection for CVE-2025-4275 (UEFI)
* VulHunt detections for multiple vulnerabilities across different ecosystems:
* `CVE-2024-54085` (LUA)
* `CVE-2018-18313` (POSIX)
* `CVE-2022-40674` (POSIX)
* `CVE-2023-26604` (POSIX)
* `CVE-2024-10237` (POSIX)
* `CVE-2024-6387` (POSIX)
* `CVE-2024-8096` (POSIX)
* `CVE-2025-0840` (POSIX)
* `CVE-2025-32463` (POSIX)
* `CVE-2025-7937` (POSIX)
* `BRLY-2025-003` (UEFI)
* `BRLY-2025-004` (UEFI)
* `CVE-2023-40238` (UEFI)
* `CVE-2025-3052` (UEFI)
* `CVE-2025-33043` (UEFI)
* `CVE-2025-4421` (UEFI)
* `CVE-2025-4422` (UEFI)
* `CVE-2025-4423` (UEFI)
* `CVE-2025-4424` (UEFI)
* `CVE-2025-4425` (UEFI)
* `CVE-2025-4426` (UEFI)
* `CVE-2025-7026` (UEFI)
* `CVE-2025-7027` (UEFI)
* `CVE-2025-7028` (UEFI)
* `CVE-2025-7029` (UEFI)
* YaraHunt detections for the following:
* Vulnerabilities:
* CVE-2025-6198 (POSIX)
* Supply-chain issues:
* eslint-config-prettier compromise (JavaScript/NPM)
* SSHDoor (OpenSSH backdoor)
* XZ-utils backdoor
* UEFI Bootkits:
* [UEFI Bootkit Hunting: In-Depth Search for Unique Code Behavior](https://www.binarly.io/blog/uefi-bootkit-hunting-in-depth-search-for-unique-code-behavior)
* **Analysis Framework Enhancements**
* Multiple engine and rule format improvements including new features and bug fixes
* Multiple improvements to the internal static analysis framework and decompiler
* Support for rule/match confidence
* Improved caching of analysis results
# 3.50.1+2026.06.17
Source: https://docs.binarly.io/release-notes/v3.50.1
Binarly v3.50.1 release notes: RPM dependency vulnerability detection for RockyLinux ISO images, debug symbol exclusion, dependencies grid fix.
## Binarly Analysis Engine
* **New Platforms/Formats**
* Added support for RPM packages extracted from RockyLinux ISO images, enabling dependency vulnerability detection for RockyLinux-based systems.
* **Analysis Framework Enhancements**
* Debug symbol files (`.build-id/*`) are now excluded from component analysis, reducing scan size and improving performance on images built with debug information.
## Bug Fixes
### Dependencies
* **Filter by fix**: Fixed missing filter on the dependencies grid that prevented filtering by fix availability.
# 3.53.0+2026.06.23
Source: https://docs.binarly.io/release-notes/v3.53.0
Binarly v3.53.0 release notes: MCUboot bootloader and Zephyr firmware analysis support, plus CVEHunt dependency scanning for MCUboot, Zephyr, U-Boot.
## Binarly Analysis Engine
* **New Platforms/Formats**
* Added support for unpacking MCUboot bootloader and Zephyr firmware components.
* CVEHunt now scans MCUboot, Zephyr, and U-Boot components for known dependency vulnerabilities.
* Added Zephyr version identification to support dependency vulnerability matching.
# 3.53.4+2026.07.01
Source: https://docs.binarly.io/release-notes/v3.53.4
Binarly v3.53.4 release notes: new UEFI detections for writable SPI flash and Secure Boot Setup Mode, VulHunt U-Boot coverage, and apk package support.
## Binarly Analysis Engine
* **New Platforms/Formats**
* Added support for apk packages when processing Docker images.
* **Vulnerability Database Service**
* Added Debian as a vulnerability advisory data source.
* Added RockyLinux as a vulnerability advisory data source.
* **New Context-Aware Rule Detection**
* Added VulHunt detection for vulnerabilities in U-Boot.
* Added detection for SPI flash regions that are expected to be write-protected but remain writable by the host firmware (BIOS).
* Added detection for Secure Boot Setup Mode being enabled, which lets a local attacker enrol a Platform Key and take ownership of Secure Boot.
* **Analysis Framework Enhancements**
* Firmware unpacking now extracts flash descriptors from UEFI firmware.
* Package information now propagates across duplicate components, improving package identification accuracy.
## Bug Fixes
### Platform
* **User settings**: Fixed a routing error that caused the user settings page to return a "not found" error.
# 3.56.2+2026.07.09
Source: https://docs.binarly.io/release-notes/v3.56.2
Binarly v3.56.2 release notes: risk score in the findings grid, Code and Environment Reachability columns, Alpine vulnerability advisory source, plus bug fixes.
## Hero Features
* **Risk score**
* Every finding now carries a single risk score that folds exploitation, impact, decision, and finding-type signals into one number, so you can work the list from most to least urgent instead of weighing CVSS, EPSS, KEV, and reachability by hand.
* The global and image findings grids order by risk score by default. Switch between three profiles, Balanced, Exploitability, and Actionable Risk (the default), to match a baseline review, threat hunting, or remediation planning.
* Learn more in [Prioritizing with the Risk Score](/user-guides/image-scans/risk-score) and [Binarly Risk Score](/resource-center/binarly-risk-score).
* **Code and Environment Reachability**
* Two reachability columns replace the legacy Reachable column. Code Reachability shows whether the vulnerable code is reachable inside its binary; Environment Reachability shows whether the component runs or loads in the deployed environment. Read together, they scope the grid to the findings that actually execute.
* Reachability also appears on each finding's details page, with the components the reachability comes from. Filter and combine both columns to build a reachable-findings triage view. See [Filtering findings by reachability](/user-guides/image-scans/reachability-filtering) and [Reachability analysis (ASAP)](/resource-center/asap).
## Features
* **Code Reachability in the findings grid API**: The findings grid API now returns Code Reachability, so you can query and filter findings by reachability programmatically.
## Binarly Analysis Engine
* **Vulnerability Database Service**
* Added Alpine as a vulnerability advisory data source.
## Bug Fixes
### Platform
* **Dashboard charts**: Fixed a cross-site scripting (XSS) vulnerability in the dashboard's charting library.
* **Findings report download**: Fixed an error that caused findings report downloads to fail when a risk filter was applied.
* **Aggregation refreshes**: A server restart could leave a product's aggregation refresh stranded, so aggregated finding data stayed stale. These operations are now reclaimed and reprocessed.
### Firmware analysis
* **Git repository scans**: Scans of images containing corrupted or invalid git repositories no longer fail with processing exceptions.
# 3.57.3+2026.07.13
Source: https://docs.binarly.io/release-notes/v3.57.3
Binarly v3.57.3 release notes: bug fixes for finding details, vulnerable code snippet retrieval, report formatting, and reachability display.
## Bug Fixes
### Platform
* **Vulnerable code snippet retrieval**: Fixed an issue where retrieving and analyzing the vulnerable code snippet failed for certain findings.
* **Finding details page**: Fixed a 404 error when opening a finding's details page.
* **Report Impact section**: Fixed incorrect text formatting in the Impact section of findings reports.
* **Code and Environment Reachability display**: Findings with multiple Code Reachability or Environment Reachability values now show an ellipsis in the findings grid instead of a count alongside the CR/ER labels.
# 3.59.0+2026.07.14
Source: https://docs.binarly.io/release-notes/v3.59.0
Binarly v3.59.0 release notes: saved filters now use Code Reachability, plus a severity column bug fix.
## Features
* **Saved filters use Code Reachability**: Saved filters and sorting that referenced isReachable now use Code Reachability.
## Bug Fixes
### Platform
* **Severity column position**: Severity now sits next to the other metrics, like CVSS, since risk score became a default column.
# v3.6
Source: https://docs.binarly.io/release-notes/v3.6
We’re excited to introduce major enhancements to the Binarly Transparency Platform.
Today we’re rolling out Binarly Transparency Platform 3.6, with powerful new capabilities designed to help teams focus faster, reduce noise, and expand visibility across analyzed binaries.
## Hero Features
* **Findings Scope**
* Focus on the most relevant issues on a per-product basis with comprehensive scoping filters.
* Scope filters allow tailoring the findings view to match each product's specific requirements.
* Filters apply to the dashboard, findings grid, charts, and exports.
* **Python package and source code analysis support**
* PQC and CBoM: identification of cryptographic algorithms and libraries
* Extends our existing capabilities for cryptographic inventory analysis to the Python ecosystem
* **Filter by CVSS Vector elements**
* Findings Grid is now able to filter by all CVSS Vector elements
* Integration with saved views and column management
* Default filter is the CVSSv3 Base Score and Attack Vector
## Features
* **Binarly Knowledge Center Integration**
* Access to the Binarly Knowledge Center directly from the Binarly Platform UI
* Guides, tutorials, and best practices for using the Binarly Platform
* Integration
* SaaS: available by default
* On-prem: available but needs to be enabled server-side
* **Scan partitioning (50 MB partitions)**
* Small images are unaffected
* Large images see 20 - 50% performance improvement, depending on size and component makeup
* Computation of scans is now parallelised across many nodes
## Binarly Analysis Engine
* **New Platforms/Formats**
* Support for disk images in various formats (raw, VHD, VHDX, QCOW2, VMDK)
* Support for Python packages, source code, and byte code, with installation and source provenance
* **Vulnerability Database Service**
* Improvements and fixes for cisa-kev, metasploit, and nuclei sources
* Performance and stability improvements including faster Ubuntu OVAL updates and git repository synchronization
* **New Features**
* Known vulnerability detection:
* New rule primitives for control-flow analysis and IR matching
* Improved decompilation matching via constraints
* Documentation additions and improvements in preparation for VulHunt community edition release at RE//verse
* Cryptographic assets/algorithms:
* Cryptographic algorithm identification for Python packages and source code:
* Support for major libraries, including: stdlib, cryptography, m2crypto, pycryptodome, pynacl, and pyopenssl
* CBoM generation support
* Additional cryptographic algorithm coverage for the Java ecosystem
* Support for estimated EPSS (E-EPSS) for cryptographic weaknesses, Secure Boot bypasses, use of leaked keys, and incorrectly implemented or missing RSB stuffing
* **New Context-Aware Rule Detection (VulHunt, FwHunt, YARA)**
* VulHunt detection(s) for:
* CVE-2024-12084 (POSIX)
* **Analysis Framework Enhancements**
* Support for analyzing and creating partitioned analysis archives for improved scan performance and resource utilization
* Support for inter-tool property communication, so that analysis tools in the scan pipeline can transmit properties to each other, allowing, e.g., to derive inter-component reachability or to model the effect of hardening features on a finding's severity
* Improved analysis of binaries compiled with Pointer Authentication Code (PAC)
* Improved handling of padding bytes when performing disassembly
* Improved compiler identification in POSIX/UEFI binaries, including fixes for clang-compiled UEFI modules and enhanced rustc detection
* Improved type system support for incomplete arrays and flex array members
* Stricter ARM alignment checks during CFG construction, reducing false positives and improving coverage
* Improved support for cryptographic keys extraction
* 7-15% performance improvement for cryptographic algorithm identification for Java ecosystem
* Improved memory utilization during analysis archive creation (input extraction and normalisation)
* Updated reporting APIs to enable package-level properties
* Fixes for analysis of standalone UEFI modules in FwHunt rule engine
* Fixes for RSB stuffing checker
# 3.63.3+2026.07.21
Source: https://docs.binarly.io/release-notes/v3.63.3
Binarly v3.63.3 release notes: license info in apk and rpm package details, updated severity tags, a Product Admin upload fix, and an Activity tab crash fix.
## Features
* **Severity tags**: Findings grid severity tags for older scores now match the current design specs.
## Binarly Analysis Engine
* **Analysis Framework Enhancements**
* Package details for `apk` and `rpm` packages now include license information.
## Bug Fixes
### Reports
* **Grid N/A display**: N/A now displays consistently in uppercase across grid results, replacing a mix of lowercase and uppercase.
* **No-data report message**: Reports now show an updated message when there is no data to display.
### Platform
* **Finding activity tab**: Fixed a crash that turned the screen black when viewing a finding's activity tab.
* **Product Admin uploads**: Fixed an issue where the Product Admin role could not upload within a Product. The upload button appeared active but the operation never completed.
### Analysis Engine
* **SMM finding labeling**: Fixed SMM vulnerability findings that were labeled `smram-write-via-global-buffer` instead of the correct `smram-write-via-protocol`.
* **Python package components**: Fixed an issue where virtual components were incorrectly included when building Python package components from git repositories.
* **Vulnerability Database Service**: Fixed two bugs in the Vulnerability Database Service.
# 3.66.0+2026.07.28
Source: https://docs.binarly.io/release-notes/v3.66.0
Binarly v3.66.0 release notes: Environment Reachability enabled for all platform instances, Linux kernel ELF support, and a new CVE-2026-43499 detection rule.
## Features
* **Findings grid: risk-factored columns hidden**: KEV, EPSS, and EMS no longer appear as separate columns by default, since Risk Score already factors them in.
* **Global findings grid: data varies by finding type**: The global findings grid now shows more relevant data for each finding based on its type.
* **Images grid: default sort by version**: Images now sort by version, then upload date, instead of upload date alone.
* **Images grid: multi-column sorting**: Sort images by up to 5 columns at once, matching the findings grid.
* **Faster scan finalization**: Scans finish processing more quickly.
## Binarly Analysis Engine
* **New Platforms/Formats**
* The platform now extracts U-Boot environment data from firmware images.
* The platform now unpacks Linux kernel ELF components (`vmlinux`) for downstream analysis.
* VulHunt now detects vulnerabilities within Linux kernel ELF binaries. Firmware containing Linux kernel ELF components may take longer to scan.
* **Vulnerability Database Service**
* Added RedHat as a vulnerability data source.
* **New Context-Aware Rule Detection (VulHunt, Mitigate)**
* Added VulHunt detection for CVE-2026-43499 (GhostLock) in Linux kernel ELF files.
* Added a Mitigate check for U-Boot images where the `bootdelay` configuration leaves the boot console accessible without authentication (CWE-306, CWE-489, CVSS 7.6).
* **Analysis Framework Enhancements**
* Environment Reachability and Code Reachability are now permanently enabled for all platform instances. The rollout flag that previously gated these findings grid columns has been removed.
## Bug Fixes
### Reports
* **N/A formatting**: N/A now displays consistently in uppercase in reports.
### Platform
* **Version button display**: The version button now shows the release date by default instead of the full version string, which could overflow.
* **Dashboard TIM widget**: Fixed a display issue with the TIM widget on the Dashboard.
# 3.68.1+2026.08.04
Source: https://docs.binarly.io/release-notes/v3.68.1
Binarly v3.68.1 release notes: PQC Compliance reachability display update, RPM package details for generic image scans, and a fix for vulnerability source prioritization.
## Features
* **PQC Compliance report reachability**: The PQC Compliance report now shows Code Reachability using the same tags as the detailed image report, instead of only Yes or Undetermined.
* **Code size limit visibility**: The configured code size limit is now visible in the platform UI.
## Binarly Analysis Engine
* **Analysis Framework Enhancements**
* Generic image scans now attach RPM package details (name, version, vendor) to the components they extract.
## Bug Fixes
### API
* **Bulk file deletion**: Fixed a server error that prevented deleting uploaded files, such as debug symbols, through the bulk delete API endpoint.
### Findings
* **Vulnerability source prioritization**: Fixed a regression where newly scanned images stopped reporting variant data under bare source keys, which caused configured vulnerability source prioritization to stop applying.
* **CVE description formatting**: Fixed CVE descriptions that displayed without spaces between words.
### Platform
* **Findings Trend chart ordering**: Fixed incorrect data ordering across all tabs of the Findings Trend chart.
# 3.75.0+2026.08.11
Source: https://docs.binarly.io/release-notes/v3.75.0
Binarly v3.75.0 release notes: environment-aware risk scoring, new Alpine/Debian/Rocky Linux vulnerability data sources, and VulHunt detection for BRLY-2026-044 in BMC firmware.
## Hero Features
* **Environment-aware risk scoring**: The risk score formula now factors in environment reachability.
* **Expanded vulnerability data sources**: Alpine, Debian, and Rocky Linux are now available as vulnerability data sources.
## Features
* **Component tree search**: You can now search for components in the All components tab.
## Binarly Analysis Engine
* **New Platforms/Formats**
* Generic image scans now extract U-Boot data.
* **Analysis Framework Enhancements**
* CveHunt now recognizes package and ecosystem information for Linux kernel ELF components, improving vulnerability match accuracy and reducing false positives.
* **New Context-Aware Rule Detection (VulHunt)**
* Added VulHunt detection for BRLY-2026-044 in BMC firmware.
# 3.8.1+2026.04.01
Source: https://docs.binarly.io/release-notes/v3.8.1
Binarly v3.8.1 release notes: redesigned finding details, variants management, an AI triage assistant, and CycloneDX SBOM enrichment.
Starting with this release, Binarly ships on a weekly cadence using semantic versioning. Versions follow the format `MAJOR.MINOR.PATCH+YYYY.MM.DD`, where the build metadata suffix is the release date. The version shown in the platform UI matches this identifier.
## Hero Features
* **Finding Variants**: [User guide](/user-guides/image-scans/finding-variants)
* Configure a prioritized list of alternative vulnerability data sources per product. When a matching variant exists, its attributes override the corresponding finding attributes
* A dedicated Variants tab on the finding details page shows all available variants and their source attribution, with the currently applied variant marked
* Variant state is reflected consistently across the findings grid, JSON exports, and finding escalations
* **Redesigned Finding Details Page**
* New right side panel shows finding details and key metrics at a glance, without leaving the findings grid
* Integrated search bar on the finding details page for navigating content across sections
* Structured information cards for References, Escalations, Notes, Description, PQC Compliance, Structured Data Evidence, Code Listing Evidence, and Finding Instances
* Reports and Actions menus consolidate report generation and common operations into a single location
* Copy content menus on finding cards and evidence sections enable quick extraction in Markdown, JSON, or clipboard format
## Features
### Compliance
* **CycloneDX SBOM Compliance & Enrichment**
* SBOM exports now include CVSS severity, references, variants, and CWE data for each vulnerability
* Every BOM is assigned a unique URN UUID serial number per the CycloneDX specification
* CycloneDX metadata now includes the post-build lifecycle phase and the version of the analyzed image
### Triage
* **AI Assistant**
* AI Assistant button on the finding page opens the triage drawer with the first contextual suggestion pre-applied. Only shown when suggestions are available
* **SSVC and CVSS Display**
* SSVC metric section on the finding page redesigned for clarity
* CVSS v4 scores are now formatted and displayed correctly, with the version prefix shown for all CVSS v2/v3/v4 entries
### API
* **BA2 Download API**
* New API endpoint for direct download of BA2 analysis archive files; accessible from VulHunt Jupyter notebooks and external workflows
* **Sources Management API**
* New endpoints for listing and editing sources and exposing variant application policy operations for automation workflows
### Platform
* **Scope Status Auto-Refresh**
* Scope status indicators on product and finding pages refresh automatically
* **Organization Page Access**
* Organization pages are now read-only accessible to all Org Users, not only via direct link
* **Transparent Platform Versioning**
* The UI now displays the date-based release version for easy correlation with deployment history
## VulHunt Community Edition
The Binarly research team launched [VulHunt Community Edition](https://vulhunt.re) alongside this release, an open-source binary vulnerability hunting tool.
VulHunt uses dataflow analysis and Weggli-based code pattern matching rather than signature matching or version inference. Write Lua-based rules, scan binaries, and get findings annotated at exact instruction addresses in decompiled code. Supports x86 and ARM (32/64-bit) for POSIX binaries and UEFI firmware.
* Taint tracking and dataflow analysis for command injection, buffer overflows, and use-after-free
* Architecture-independent code pattern matching on decompiled output
* LLM integration via MCP for automated triage and rule generation
* Integration with Binary Ninja and the Binarly Transparency Platform
Install via one-liner, Docker, or from source on Linux, macOS, and Windows. See [vulhunt.re](https://vulhunt.re) for documentation and rules.
# 3.80.0+2026.08.18
Source: https://docs.binarly.io/release-notes/v3.80.0
Binarly v3.80.0 release notes: generated VulHunt rules now run during scans, package dependency data on findings, and a findings 404 redirect fix.
## Hero Features
* **Expanded VulHunt vulnerability detection**: Scans now run an additional set of generated VulHunt rules. Matches from these rules appear as Known Vulnerability findings alongside the existing VulHunt results.
## Binarly Analysis Engine
* **Vulnerability Database Service**
* Known vulnerability findings now record whether the affected dependency was treated as a supported package dependency, so you can tell whether the reported fixed version is a package version.
## Bug Fixes
### Findings
* **Findings with missing occurrences**: Fixed a redirect that forced a 404 page when you opened a finding whose occurrence data was missing.
# 3.83.0+2026.08.25
Source: https://docs.binarly.io/release-notes/v3.83.0
Binarly v3.83.0 release notes: analysed components on the image overview, a reduced analysis coverage tab, and a finding ID column in the findings grid.
## Hero Features
* **Analysed components on the product image overview**: The image overview now reports analysed components in place of the raw component count, so you can see how much of the image was actually analysed.
* **Reduced analysis coverage tab**: A new tab lists the components that were left out of analysis. Each entry shows the component name, code size, path, and the reason it was excluded. Name and path are filterable, code size is sortable.
## Features
* **Finding ID column**: The findings grid now has a finding ID column, and the same identifier appears in image details and in exports, so you can take an ID from a CSV or JSON export and find that finding in the UI. The column can be filtered.
* **High confidence findings filter**: A built-in high confidence filter is now the default in every tenant, so you no longer have to build one yourself.
* **Code size in the components grid**: The components grid can be filtered and sorted by code size limit.
* **Analysed components in the components chart API**: The components chart endpoint now returns the analysed component count alongside components with and without findings.
* **Components grid API for excluded components**: A new grid endpoint lists components excluded from analysis with name, code size, path, and reason, with totals and pagination.
## Binarly Analysis Engine
* **Vulnerability Database Service**
* Added RPM version schema support, so version comparisons for RPM based distributions are handled correctly during vulnerability matching.
* **Analysis Framework Enhancements**
* Instruction handling was extended to cover BTI instructions on AArch64 and to treat `endbr` as a landing pad on x86, which improves analysis quality across the analysis tools.
* CryptoScan analysis of Java components completes faster on large images.
## Bug Fixes
### Findings
* **Duplicated package dependency findings**: Known vulnerability findings identified from a Linux package were reported once per CPE vendor variant of that package, producing duplicate findings for the same vulnerability. Each vulnerability is now reported once.
* **RXSA identifiers**: RXSA identifiers on the finding variants tab now link to the Rocky Linux errata page, matching the existing RLSA, RLBA, and RLEA behaviour.
### Products
* **Upload button**: Fixed the upload button in the bottom left of the product grid, which did not let you complete an upload.
### Analysis
* **Analysis crash**: Fixed a crash in instruction decoding that could interrupt analysis.
# 3.89.0+2026.09.01
Source: https://docs.binarly.io/release-notes/v3.89.0
Binarly v3.89.0 release notes: CPE and PURL in dependency identity, Cisco and Fortinet firmware unpacking, and IBM Cloud API key detection.
## Hero Features
* **CPE and PURL in dependency identity**: Dependencies are now identified by their CPE and PURL alongside vendor, product, version, license, and linkage. Two dependencies that share a name but carry different package identifiers stay separate, each with its own advisory sources, known vulnerabilities, and known fixed versions. Existing product dependencies were backfilled with their CPE and PURL identifiers.
## Binarly Analysis Engine
* **New Platforms/Formats**
* Firmware unpacking now supports Cisco CSP.
* Firmware unpacking now supports Cisco ASDM.
* Firmware unpacking now supports Cisco SGZ archives.
* Firmware unpacking now supports Fortinet FortiOS.
* **Vulnerability Database Service**
* GHSA and Go advisory aliases are now deduplicated, so a vulnerability that carries both is reported once.
* **New Features**
* Secrets scanning now detects IBM Cloud API keys and reports their validity status.
* **Analysis Framework Enhancements**
* Control flow graph reconstruction was improved, making file loading up to 30% faster across the analysis tools.
## Bug Fixes
### Findings
* **Reachability columns in CSV exports**: The findings CSV export reported an `isReachable` column instead of the Code Reachability and Environment Reachability columns used in the findings grid and reports. The export now reports both.
* **Component information in JSON exports**: Filtered findings exported in detailed JSON format from the image findings grid were missing component information for some finding types, including mitigation failures and suspicious code. Component information is now included.
* **Linux kernel package vulnerabilities**: When a Linux kernel image carried package metadata, known vulnerabilities for the kernel were still sourced from NVD instead of from the kernel package. Kernel images with package metadata are now matched to the kernel package.
### Products
* **Empty image uploads**: An image with no content could be uploaded through the API and passed to a scan. Empty uploads are now rejected.
### UI
* **Code size limit documentation link**: Updated the code size limit documentation link in the dashboard.
# Accuracy & Confidence in Findings
Source: https://docs.binarly.io/resource-center/accuracy-confidence
## Confidence Levels
BTP assigns confidence levels to findings based on the detection method and validation process. These confidence levels help users understand the reliability of each finding. Confidence levels are shown the findings grids and in the details of each finding. They can also be found in the majority of the reporting and SBOM outputs.
### Confidence Level Scale
| Confidence | LevelPercentile | ValueNumerical | ValueDescription |
| ------------------- | --------------- | -------------- | -------------------------------------------------------- |
| certain | 81% - 100% | 0.81 - 1.0 | Highest confidence, thoroughly validated findings |
| somewhat\_certain | 61% - 80% | 0.61 - 0.8 | High confidence with minimal false positive potential |
| somewhat\_uncertain | 41% - 60% | 0.41 - 0.6 | Moderate confidence, may require manual validation |
| uncertain | 21% - 40% | 0.21 - 0.4 | Lower confidence, higher false positive potential |
| very\_uncertain | 1% - 20% | 0.01 - 0.2 | Lowest confidence, requires thorough manual verification |
### Calculation Methods
The confidence levels are determined through different methods depending on the type of detection:
* **Known Vulnerabilities:** Tested on large datasets with verified results, typically achieving "certain" confidence levels
* **Secret Scanning:** Uses regex-based rules, typically assigned "somewhat\_uncertain" due to potential false positives
* **UEFI Unknown Detection:** Validated through large-scale analysis of Dell firmware, achieving \~95% precision after manual analysis
### JSON Example
```
{
"component_id": "7e0a0a8e-2bd5-4400-97b6-de1125562f67",
"name": "suspicious/posix/entrypoint",
"confidence": 0.8,
"kind": {
"kind": "finding",
"value": {
"severity": "low",
"identifiers": [],
"classifications": [],
"metrics": [],
"predicates": [],
"description": "The entry point of the ELF binary has been potentially modified",
"evidence": []
}
}
}
```
### Key Considerations
The confidence levels are assigned based on:
* Detection method reliability
* Historical accuracy of the detection mechanism
* Potential for false positives
* Need for manual validation
* Complexity of the detection process
These confidence levels are continuously refined based on feedback and validation results to improve accuracy over time.
# Cryptographic Algorithm Detection Reference
Source: https://docs.binarly.io/resource-center/algorithm-compliance
Full reference of cryptographic algorithms, protocols, and certificate issues detected by BTP, with classification status and NIST IR 8547 PQC compliance assessment.
BTP detects cryptographic algorithms, protocols, and certificate issues across six categories during static binary analysis. Each detected algorithm is assigned a classification status based on its cryptographic strength and industry guidance.
**Active compliance reporting is scoped to NIST IR 8547 (post-quantum cryptography).** The Weak and Deprecated classifications are informational, derived from industry consensus (NIST SP 800-131A, RFC 7568, RFC 8996) - BTP does not generate compliance reports against those standards.
## Detection Coverage
| Category | Detected By |
| --------------------- | --------------------------------------------------------- |
| Encryption algorithms | Code analysis (native) / API detection (managed runtimes) |
| Hashing algorithms | Code analysis (native) / API detection (managed runtimes) |
| Signing algorithms | Code analysis (native) / API detection (managed runtimes) |
| MAC algorithms | Code analysis (native) / API detection (managed runtimes) |
| Protocols | API detection |
| Certificate issues | X.509 DER/PEM structure parsing |
See [Cryptographic Detection](/resource-center/cryptographic-detection) for how detection works by binary type.
## Classification
| Status | Meaning |
| ---------------------- | ------------------------------------------------------------------------- |
| **Current** | No known weaknesses; suitable for new designs |
| **Acceptable** | No active vulnerabilities; not recommended for new designs |
| **Deprecated** | Formally deprecated by a standards body; migrate away |
| **Weak** | Known cryptographic weaknesses; avoid in all contexts |
| **Insecure** | Actively prohibited; no safe usage |
| **Quantum-vulnerable** | Secure against classical attacks; vulnerable to CRQC via Shor's algorithm |
| **PQC Compliant** | Quantum-resistant per NIST IR 8547 |
| **Informative** | Non-security-relevant; inventory only, no severity assigned |
## Encryption Algorithms
| Algorithm | Class | Status | Notes |
| ---------------- | ---------------------------------------- | ------------------ | --------------------------------------------- |
| AES | `crypto/algorithm/encryption/aes` | Current | Key size ≥128-bit; preferred symmetric cipher |
| Salsa20 | `crypto/algorithm/encryption/salsa20` | Current | Modern stream cipher |
| Twofish | `crypto/algorithm/encryption/twofish` | Acceptable | Not widely standardized |
| Camellia | `crypto/algorithm/encryption/camellia` | Acceptable | ISO/IEC 18033-3 standardized |
| 3DES | `crypto/algorithm/encryption/3des` | Deprecated | NIST SP 800-131A |
| DES | `crypto/algorithm/encryption/des` | Weak | 56-bit key |
| Blowfish | `crypto/algorithm/encryption/blowfish` | Weak | 64-bit block size; birthday attack risk |
| CAST5 | `crypto/algorithm/encryption/cast5` | Weak | 64-bit block size |
| IDEA | `crypto/algorithm/encryption/idea` | Weak | 64-bit block size |
| RC2 | `crypto/algorithm/encryption/rc2` | Weak | Multiple known attacks |
| RC4 | `crypto/algorithm/encryption/rc4` | Weak | Prohibited in TLS (RFC 7465) |
| RC5 | `crypto/algorithm/encryption/rc5` | Weak | — |
| RC6 | `crypto/algorithm/encryption/rc6` | Weak | — |
| Skipjack | `crypto/algorithm/encryption/skipjack` | Weak | Legacy; 80-bit key |
| TEA | `crypto/algorithm/encryption/tea` | Weak | Structural weaknesses |
| XTEA | `crypto/algorithm/encryption/xtea` | Weak | Structural weaknesses |
| XXTEA | `crypto/algorithm/encryption/xxtea` | Weak | Structural weaknesses |
| HC-128 | `crypto/algorithm/encryption/hc-128` | Informative | eSTREAM portfolio; no known breaks |
| Sosemanuk | `crypto/algorithm/encryption/sosemanuk` | Informative | eSTREAM portfolio; no known breaks |
| VEST | `crypto/algorithm/encryption/vest` | Informative | Niche; inventory only |
| Curve25519 | `crypto/algorithm/encryption/curve25519` | Quantum-vulnerable | ECDH key exchange |
| RSA (encryption) | `crypto/algorithm/encryption/rsa` | Quantum-vulnerable | Integer factorization; Shor's algorithm |
## Hashing Algorithms
| Algorithm | Class | Status | Notes |
| ----------- | ------------------------------------- | ----------- | ------------------------------------------------------- |
| SHA-256 | `crypto/algorithm/hashing/sha256` | Current | Recommended |
| SHA-384 | `crypto/algorithm/hashing/sha384` | Current | Recommended |
| SHA-512 | `crypto/algorithm/hashing/sha512` | Current | Recommended |
| SHA-512/224 | `crypto/algorithm/hashing/sha512-224` | Current | Truncated SHA-512 |
| SHA-512/256 | `crypto/algorithm/hashing/sha512-256` | Current | Truncated SHA-512 |
| SHA-224 | `crypto/algorithm/hashing/sha224` | Current | Acceptable for most uses |
| SHA3-224 | `crypto/algorithm/hashing/sha3-224` | Current | FIPS 202 |
| SHA3-256 | `crypto/algorithm/hashing/sha3-256` | Current | FIPS 202 |
| SHA3-384 | `crypto/algorithm/hashing/sha3-384` | Current | FIPS 202 |
| SHA3-512 | `crypto/algorithm/hashing/sha3-512` | Current | FIPS 202 |
| SHAKE128 | `crypto/algorithm/hashing/shake128` | Current | Extendable output; FIPS 202 |
| SHAKE256 | `crypto/algorithm/hashing/shake256` | Current | Extendable output; FIPS 202 |
| BLAKE2b | `crypto/algorithm/hashing/blake2b` | Current | High performance |
| BLAKE2s | `crypto/algorithm/hashing/blake2s` | Current | High performance |
| RIPEMD-160 | `crypto/algorithm/hashing/ripemd160` | Acceptable | Aging standard |
| SM3 | `crypto/algorithm/hashing/sm3` | Acceptable | Chinese national standard (GM/T 0004) |
| MD5 | `crypto/algorithm/hashing/md5` | Deprecated | Collision attacks demonstrated |
| SHA-1 | `crypto/algorithm/hashing/sha1` | Deprecated | NIST SP 800-131A |
| Tiger | `crypto/algorithm/hashing/tiger` | Weak | Not recommended |
| MD4 | `crypto/algorithm/hashing/md4` | Weak | Cryptographically broken |
| MD2 | `crypto/algorithm/hashing/md2` | Weak | Withdrawn |
| DJB2 | `crypto/algorithm/hashing/djb2` | Informative | Non-cryptographic; inventory only; native binaries only |
| FNV | `crypto/algorithm/hashing/fnv` | Informative | Non-cryptographic; inventory only; native binaries only |
| MurmurHash3 | `crypto/algorithm/hashing/murmur3` | Informative | Non-cryptographic; inventory only; native binaries only |
## Signing Algorithms
### Post-quantum algorithms
These algorithms are detected and classified as NIST IR 8547 compliant. Detection confirms their presence; adoption replaces quantum-vulnerable counterparts.
PQC digital signature algorithms are currently only detected in UEFI modules and certificates. These algorithms are not yet supported for detection in Java and Python managed runtimes or ELF native binaries.
| Algorithm | Class | Status | Standard |
| ------------------ | --------------------------------------------- | ------------- | ----------------------------- |
| ML-DSA-44 | `crypto/algorithm/signing/ml-dsa-44` | PQC Compliant | FIPS 204 (CRYSTALS-Dilithium) |
| ML-DSA-65 | `crypto/algorithm/signing/ml-dsa-65` | PQC Compliant | FIPS 204; recommended level |
| ML-DSA-87 | `crypto/algorithm/signing/ml-dsa-87` | PQC Compliant | FIPS 204; highest level |
| LMS | `crypto/algorithm/signing/lms` | PQC Compliant | NIST SP 800-208 (hash-based) |
| SLH-DSA-SHA2-128f | `crypto/algorithm/signing/slh-dsa-sha2-128f` | PQC Compliant | FIPS 205 (SPHINCS+) |
| SLH-DSA-SHA2-128s | `crypto/algorithm/signing/slh-dsa-sha2-128s` | PQC Compliant | FIPS 205 |
| SLH-DSA-SHA2-192f | `crypto/algorithm/signing/slh-dsa-sha2-192f` | PQC Compliant | FIPS 205 |
| SLH-DSA-SHA2-192s | `crypto/algorithm/signing/slh-dsa-sha2-192s` | PQC Compliant | FIPS 205 |
| SLH-DSA-SHA2-256f | `crypto/algorithm/signing/slh-dsa-sha2-256f` | PQC Compliant | FIPS 205 |
| SLH-DSA-SHA2-256s | `crypto/algorithm/signing/slh-dsa-sha2-256s` | PQC Compliant | FIPS 205 |
| SLH-DSA-SHAKE-128f | `crypto/algorithm/signing/slh-dsa-shake-128f` | PQC Compliant | FIPS 205 |
| SLH-DSA-SHAKE-128s | `crypto/algorithm/signing/slh-dsa-shake-128s` | PQC Compliant | FIPS 205 |
| SLH-DSA-SHAKE-192f | `crypto/algorithm/signing/slh-dsa-shake-192f` | PQC Compliant | FIPS 205 |
| SLH-DSA-SHAKE-192s | `crypto/algorithm/signing/slh-dsa-shake-192s` | PQC Compliant | FIPS 205 |
| SLH-DSA-SHAKE-256f | `crypto/algorithm/signing/slh-dsa-shake-256f` | PQC Compliant | FIPS 205 |
| SLH-DSA-SHAKE-256s | `crypto/algorithm/signing/slh-dsa-shake-256s` | PQC Compliant | FIPS 205 |
### Quantum-vulnerable algorithms
| Algorithm | Class | Status | Notes |
| -------------------------- | ----------------------------------------------------- | ------------------ | ------------------------------------ |
| ECDSA-SHA224 | `crypto/algorithm/signing/ecdsa-sha224` | Quantum-vulnerable | — |
| ECDSA-SHA256 | `crypto/algorithm/signing/ecdsa-sha256` | Quantum-vulnerable | — |
| ECDSA-SHA384 | `crypto/algorithm/signing/ecdsa-sha384` | Quantum-vulnerable | — |
| ECDSA-SHA512 | `crypto/algorithm/signing/ecdsa-sha512` | Quantum-vulnerable | — |
| ECDSA-SHA3-224 | `crypto/algorithm/signing/ecdsa-sha3-224` | Quantum-vulnerable | — |
| ECDSA-SHA3-256 | `crypto/algorithm/signing/ecdsa-sha3-256` | Quantum-vulnerable | — |
| ECDSA-SHA3-384 | `crypto/algorithm/signing/ecdsa-sha3-384` | Quantum-vulnerable | — |
| ECDSA-SHA3-512 | `crypto/algorithm/signing/ecdsa-sha3-512` | Quantum-vulnerable | — |
| ECDSA-SHA1 | `crypto/algorithm/signing/ecdsa-sha1` | Quantum-vulnerable | SHA-1 hash additionally deprecated |
| Ed25519 | `crypto/algorithm/signing/ed25519` | Quantum-vulnerable | Modern; not quantum-safe |
| Ed448 | `crypto/algorithm/signing/ed448` | Quantum-vulnerable | Modern; not quantum-safe |
| RSA | `crypto/algorithm/signing/rsa` | Quantum-vulnerable | Key size ≥2048-bit required |
| RSA-SHA224 | `crypto/algorithm/signing/rsa-sha224` | Quantum-vulnerable | — |
| RSA-SHA256 | `crypto/algorithm/signing/rsa-sha256` | Quantum-vulnerable | — |
| RSA-SHA384 | `crypto/algorithm/signing/rsa-sha384` | Quantum-vulnerable | — |
| RSA-SHA512 | `crypto/algorithm/signing/rsa-sha512` | Quantum-vulnerable | — |
| RSA-SHA512/224 | `crypto/algorithm/signing/rsa-sha512-224` | Quantum-vulnerable | — |
| RSA-SHA512/256 | `crypto/algorithm/signing/rsa-sha512-256` | Quantum-vulnerable | — |
| RSA-RIPEMD160 | `crypto/algorithm/signing/rsa-ripemd160` | Quantum-vulnerable | — |
| RSA-SM3 | `crypto/algorithm/signing/rsa-sm3` | Quantum-vulnerable | Chinese national standard |
| RSASSA-PKCS1-v1.5-SHA3-224 | `crypto/algorithm/signing/rsassa-pkcs1-v1-5-sha3-224` | Quantum-vulnerable | — |
| RSASSA-PKCS1-v1.5-SHA3-256 | `crypto/algorithm/signing/rsassa-pkcs1-v1-5-sha3-256` | Quantum-vulnerable | — |
| RSASSA-PKCS1-v1.5-SHA3-384 | `crypto/algorithm/signing/rsassa-pkcs1-v1-5-sha3-384` | Quantum-vulnerable | — |
| RSASSA-PKCS1-v1.5-SHA3-512 | `crypto/algorithm/signing/rsassa-pkcs1-v1-5-sha3-512` | Quantum-vulnerable | — |
| SM2 | `crypto/algorithm/signing/sm2` | Quantum-vulnerable | ECC-based; Chinese national standard |
### Deprecated algorithms
| Algorithm | Class | Status | Notes |
| ------------ | --------------------------------------- | ---------- | --------------------------------------- |
| DSA | `crypto/algorithm/signing/dsa` | Deprecated | NIST SP 800-131A |
| DSA-SHA1 | `crypto/algorithm/signing/dsa-sha1` | Deprecated | NIST SP 800-131A |
| DSA-SHA224 | `crypto/algorithm/signing/dsa-sha224` | Deprecated | DSA key deprecated |
| DSA-SHA256 | `crypto/algorithm/signing/dsa-sha256` | Deprecated | DSA key deprecated |
| DSA-SHA384 | `crypto/algorithm/signing/dsa-sha384` | Deprecated | DSA key deprecated |
| DSA-SHA512 | `crypto/algorithm/signing/dsa-sha512` | Deprecated | DSA key deprecated |
| DSA-SHA3-224 | `crypto/algorithm/signing/dsa-sha3-224` | Deprecated | DSA key deprecated |
| DSA-SHA3-256 | `crypto/algorithm/signing/dsa-sha3-256` | Deprecated | DSA key deprecated |
| DSA-SHA3-384 | `crypto/algorithm/signing/dsa-sha3-384` | Deprecated | DSA key deprecated |
| DSA-SHA3-512 | `crypto/algorithm/signing/dsa-sha3-512` | Deprecated | DSA key deprecated |
| RSA-SHA1 | `crypto/algorithm/signing/rsa-sha1` | Deprecated | SHA-1 hash deprecated; NIST SP 800-131A |
### Weak algorithms
| Algorithm | Class | Status | Notes |
| --------- | ---------------------------------- | ------ | ---------------------------------------------- |
| RSA-MD5 | `crypto/algorithm/signing/rsa-md5` | Weak | MD5 collision attacks enable signature forgery |
| RSA-MD2 | `crypto/algorithm/signing/rsa-md2` | Weak | MD2 withdrawn; signatures can be forged |
## MAC Algorithms
| Algorithm | Class | Status | Notes |
| --------------- | -------------------------------------- | ---------- | ------------------------------------- |
| HMAC-SHA224 | `crypto/algorithm/mac/hmac-sha224` | Current | — |
| HMAC-SHA256 | `crypto/algorithm/mac/hmac-sha256` | Current | Recommended |
| HMAC-SHA384 | `crypto/algorithm/mac/hmac-sha384` | Current | — |
| HMAC-SHA512 | `crypto/algorithm/mac/hmac-sha512` | Current | Recommended |
| HMAC-SHA512/224 | `crypto/algorithm/mac/hmac-sha512-224` | Current | Truncated SHA-512 |
| HMAC-SHA512/256 | `crypto/algorithm/mac/hmac-sha512-256` | Current | Truncated SHA-512 |
| HMAC-SHA3-224 | `crypto/algorithm/mac/hmac-sha3-224` | Current | FIPS 202 |
| HMAC-SHA3-256 | `crypto/algorithm/mac/hmac-sha3-256` | Current | FIPS 202 |
| HMAC-SHA3-384 | `crypto/algorithm/mac/hmac-sha3-384` | Current | FIPS 202 |
| HMAC-SHA3-512 | `crypto/algorithm/mac/hmac-sha3-512` | Current | FIPS 202 |
| Poly1305 | `crypto/algorithm/mac/poly1305` | Current | Used with ChaCha20 |
| HMAC-SM3 | `crypto/algorithm/mac/hmac-sm3` | Acceptable | Chinese national standard (GM/T 0004) |
| HMAC-MD5 | `crypto/algorithm/mac/hmac-md5` | Deprecated | MD5 hash deprecated |
| HMAC-SHA1 | `crypto/algorithm/mac/hmac-sha1` | Deprecated | SHA-1 deprecated; NIST SP 800-131A |
## Pseudorandom Number Generators
Detection is available for native binaries only.
| Algorithm | Class | Status | Notes |
| ---------------- | -------------------------------- | ------ | ----------------------------------------------------------------- |
| Mersenne Twister | `crypto/algorithm/prng/mersenne` | Weak | Not a CSPRNG; output is predictable given sufficient observations |
## Protocols
| Protocol | Class | Status | Reference |
| -------- | -------------------------- | ---------- | ------------------------------------ |
| TLS v1.3 | `crypto/protocol/tls/v1-3` | Current | Recommended |
| TLS v1.2 | `crypto/protocol/tls/v1-2` | Current | Acceptable with strong cipher suites |
| TLS v1.1 | `crypto/protocol/tls/v1-1` | Deprecated | RFC 8996 |
| TLS v1.0 | `crypto/protocol/tls/v1-0` | Deprecated | RFC 8996 |
| SSL v3.0 | `crypto/protocol/ssl/v3-0` | Insecure | RFC 7568 (POODLE) |
| SSL v2.0 | `crypto/protocol/ssl/v2-0` | Insecure | RFC 6176 |
## Certificate Issues
| Issue | Class | Severity | Notes |
| ----------------------- | -------------------------------- | -------- | ---------------------------------- |
| Expired certificate | `crypto/certificate/expired` | High | Validity period has passed |
| Invalid certificate | `crypto/certificate/invalid` | High | Invalid parameters or structure |
| Weak RSA key parameters | `crypto/rsa/weak-key-parameters` | High | Does not meet minimum key strength |
| Self-signed certificate | `crypto/certificate/self-signed` | Medium | Not signed by a recognized CA |
| Untrusted certificate | `crypto/certificate/untrusted` | Medium | Signed by an unrecognized CA |
## PQC Compliance Assessment
BTP's active compliance reporting for cryptographic algorithms is scoped exclusively to **NIST IR 8547**. Weak and Deprecated classifications above are informational and do not constitute a compliance report.
Quantum-vulnerable algorithms remain secure against classical computers today. The risk is retroactive decryption by a future cryptographically-relevant quantum computer (CRQC) - a relevant threat for long-lived encrypted data.
BTP identifies all quantum-vulnerable algorithm instances per binary image, maps them to NIST IR 8547 guidance, and surfaces replacement recommendations. This assessment is published as the [PQC Compliance Report](/user-guides/export/pqc) (PDF and JSON).
NIST IR 8547 migration timeline:
| Timeline | Requirement |
| ---------------------- | ----------------------------------------------------- |
| Short-term (by 2030) | Inventory all quantum-vulnerable algorithm usage |
| Mid-term (2030–2035) | Transition critical systems to PQC algorithms |
| Long-term (after 2035) | Complete deprecation of quantum-vulnerable algorithms |
## Related
* [Cryptographic Detection](/resource-center/cryptographic-detection)
* [Finding Classes Reference](/resource-center/finding-classes)
* [Cryptographic Materials Tab](/user-guides/image-scans/cryptographic-materials)
* [PQC Compliance Report](/user-guides/export/pqc)
* [CBOM Export](/user-guides/export/cbom)
# Attack Surface Approximation and Prioritisation (ASAP)
Source: https://docs.binarly.io/resource-center/asap
How Binarly computes reachability across four levels, from within a single binary up to the environment-aware attack surface, to prioritise the findings that actually matter.
Whether the flaw can be reached is a reasonable proxy for how easily it can be exploited, or whether it is exploitable at all. In a static setting, reachability is neither simple to compute nor well captured by a single yes/no answer. Binarly models it across four levels, from a single function inside one binary up to the components that actually execute in a deployed package. Attack Surface Approximation and Prioritisation (ASAP) is the top level: it approximates the attack surface of a package and scopes findings to the code that runs.
Used this way, reachability complements existing severity and exploitability metrics such as CVSS, EPSS, and SSVC. Those metrics rate a vulnerability in the abstract. Reachability asks whether the vulnerable code is reachable in this artifact and under this deployment.
Reachability is a filter that preserves relevant findings. It reduces finding fatigue by scoping thousands of raw results down to the ones exposed to the assumed attack surface, without discarding data through naive allow/deny filtering.
## Definitions
| Term | Meaning |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Container** | A collection of software components and artifacts. |
| **Component** | A single piece of software: an executable, shared library, or firmware blob. |
| **Artifact** | A non-software file or blob inside a container. |
| **Environment** | A configuration of components and artifacts that determines which components load, which runs first, and how components interact with each other, with artifacts, and with the outside world. It may include a component loader and mechanisms for restricting interactions. |
| **Entry-point** | A location within a component where execution can start, such as an executable's `main` function or a shared library's exported function. It may or may not be advertised to other components or the program loader. |
## The reachability hierarchy
Binarly answers three progressively broader questions about a finding, then combines the answers in ASAP:
Is this vulnerable location reachable from a well-known entry-point of the binary it lives in?
Is this vulnerable library function actually called by another component?
Is this vulnerable component actually executed or loaded under the package's assumed configuration?
Combine the levels above to approximate the relevant attack surface: any component and code that runs or loads and is reachable with respect to the assumed runtime environment and inter-component reachability.
## Intra-component reachability
A component does not run all at once. A vulnerability sits at some location in its code, and that location is only a concern if execution can actually reach it. Binarly statically analyses each component to determine whether a vulnerable location is reachable from an entry-point, resolving indirect control flow where it can and reporting conservatively where it cannot.
Entry-points depend on the component and platform:
* A shared library's exported functions.
* An executable's `start` or `main` function.
* For UEFI, a driver or module's protocol interfaces, PPIs, registered event handlers, and identified SMI handlers.
* For firmware with an Interrupt Vector Table, the defined Interrupt Service Routines.
Each reachable location is classified by the kind of entry-point it is reachable from.
### Classifying reachability
Reported from high to low risk:
| Class | Meaning |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Entrypoint** | A path exists from the component's original entry-point (such as `main` or `start`) to the vulnerable location. |
| **Exported** | Indirect reachability from a viable exported entry-point. For shared libraries this means exported functions; for UEFI it covers identified SMI handlers and functions in registered protocol interfaces and PPIs. |
| **Referenced** | The location is referenced by code that is reachable from an entrypoint or exported function, but exact reachability cannot be determined statically. |
| **Undetermined** | Reachability cannot be determined statically. |
Alongside the class, Binarly provides trace evidence: one or more paths showing that the location is reachable, and a measure of how hard it is to reach.
In the platform, these classes appear in the Code Reachability column. Findings with no analysable code show N/A. See [Filtering findings by reachability](/user-guides/image-scans/reachability-filtering).
Improving reachability accuracy is ongoing work for the Binarly research team. Intra-component reachability is reported for platforms where Binarly performs in-depth code analysis.
## Inter-component reachability
A component does not run in isolation. Binarly determines how components call each other's exported functions, so an exported function counts as a viable entry-point when another component calls it. This shows how a vulnerable component affects the components that depend on it: if `ApplicationX` links to `LibraryY` and calls `vuln_fcn1`, and `LibraryY` links to `LibraryZ` and calls `vuln_fcn2`, then `ApplicationX` is affected by `{vuln_fcn1, vuln_fcn2}`.
Libraries loaded at runtime are included where that use can be identified statically.
## Environment-aware reachability
An execution environment holds both software components and artifacts. Artifacts may be regular files, but some configure the runtime. In an embedded Linux environment, boot scripts determine which components load and run during initialisation. That list, together with later component-specific configuration files, determines the set of components that can run. Binarly may not determine this set exactly, but it approximates it and uses the result to mark which component entry-points are viable.
Binarly approximates which components run from the package configuration:
* **Containers**, from the OCI image configuration: the `Entrypoint`, `Cmd`, and `Env` properties determine what launches when the container starts.
* **Linux-like firmware and system images**, from standard start-up scripts such as those under `/etc/init.d/`.
* **System firmware**, from the firmware image structure, for example the modules present in a UEFI firmware image.
From these seeds, Binarly discovers which components execute and what they depend on, then propagates that information to downstream analyses so each finding carries its reachability context.
## ASAP: approximating the attack surface
ASAP combines the levels above into a single question: given the components that will run or load, and how they reach each other, which findings sit on the relevant attack surface? Everything else can be filtered out or de-prioritised.
The relevant attack surface is any component and code that runs or loads and is reachable with respect to the assumed runtime environment and inter-component reachability.
![Diagram of the ASAP attack surface: components reachable from actual entry points stay in scope while components that never execute are pushed out.]()
On production containers and images, scoping findings to the ASAP attack surface reduces the count of findings to assess by roughly an order of magnitude, depending on container or image size. The same computation supports a fast-scan configuration: analyse in depth only the components assumed to be reachable.
### How ASAP discovers reachable components
ASAP determines which components are likely to execute under a given configuration. Each supported package type has a default policy for which components are assumed to execute first. From there, ASAP follows each component's runtime dependencies and the components it invokes, adds the newly discovered components, and repeats until no new components are found.
### The environment reachability metric
For each component that may execute under ASAP's assumptions, the reachability is attached to every finding on that component. Each result records the environment it was derived from, the reachability kind, and a confidence value.
The environment classes are:
| Environment | Meaning |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Container** | A container image, such as a Docker container. |
| **System image** | A disk image of an OS installation. |
| **System firmware** | A firmware image, such as a UEFI firmware image. |
| **Undetermined** | The environment could not be determined precisely, for example a BMC firmware image that resembles a generic Linux image. |
A component reachable from more than one other component carries more than one result, each naming the referent component it is reachable from. Components outside the assumed attack surface are reported as undetermined. In the findings grid and finding detail these appear as the Environment Reachability values and their from Component(s) list.
The reachability kinds are:
| Kind | Meaning |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Entrypoint** | Reachable from the advertised environment entry-point, such as a container's entrypoint. |
| **Runtime Invocation** | Reachable because another component may invoke it at runtime. The referent identifies the invoking component. |
| **Runtime Dependency** | Reachable because another component may load it as a dependency, for example through dynamic linking. The referent identifies the depending component. |
| **Undetermined** | Reachability could not be determined, or the component is outside the assumed attack surface. |
## Where reachability is used
Reachability is a reweighting factor for existing severity and exploitability metrics. Binarly applies it across four areas:
| Area | How reachability is used |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Triage prioritisation | Orders which vulnerabilities to assess first, highest risk first. |
| Remediation prioritisation | Orders which vulnerabilities to patch first. |
| Third-party component risk | Scales how much additional risk a vulnerable component adds in the context of a larger product, based on its reachability profile. |
| Risk reweighting | Once reachability is computed at the environment or inter-component level, it can rescore a known vulnerability's impact or severity given where the vulnerability sits within a wider product. |
Reachability answers whether a vulnerability can be triggered in your deployment. The [Exploitation Maturity Score](/resource-center/ems-escalations) adds whether it is being exploited in the wild, so the two together drive remediation priority.
![Prioritization stack: code, component, and environment reachability from ASAP, with the Exploitation Maturity Score layered on top.]()
## Reachability in the platform
Reachability appears throughout the Binarly Transparency Platform:
* On the [finding details page](/user-guides/image-scans/all-about-details), the Code Reachability and Environment Reachability results sit alongside CVSS, EPSS, EMS, and confidence to indicate exploitability.
* In the Findings grid, the Code Reachability and Environment Reachability columns each have a filter, so you can scope a view to reachable findings and combine the two. See [Filtering findings by reachability](/user-guides/image-scans/reachability-filtering).
* Reachability feeds the [Binarly Risk Score](/resource-center/binarly-risk-score): the reachability kind and confidence, for both code and environment reachability, reweight a finding's score, so reachable findings rank higher.
* Reachability data is included in exports: [VEX](/user-guides/export/vex), [CBOM](/user-guides/export/cbom), and [PQC reports](/user-guides/export/pqc).
## Reference
Reachability Analysis for Binary Executables. Matrosov, Thomas, Vasilenko. US Patent 12,287,885 B1, April 2025.
## Related
How reachability reweights a finding's risk score.
Real-world exploitation evidence that complements reachability.
The classes of finding reachability is computed for.
How Binarly reports confidence in its results.
# Binarly Risk Score
Source: https://docs.binarly.io/resource-center/binarly-risk-score
How the Binarly Risk Score turns exploitation, impact, decision, and finding-type signals into one transparent 0 to 1 priority score, with selectable profiles.
The Binarly Risk Score (BRS) combines the signals the platform already collects about a finding, CVSS, EPSS, EMS, KEV, LEV, SSVC, reachability, detection confidence, and the finding type itself, into a single normalized score between 0 and 1. A higher score means the finding deserves attention sooner.
Every input, weight, and step is open and auditable, and you can switch between scoring [profiles](#scoring-profiles) to match how your team prioritizes work.
## Why a new risk score
Single-metric scoring forces a trade-off. CVSS describes severity but says nothing about whether a vulnerability is being exploited. EPSS predicts exploitation but ignores impact and reachability. A KEV listing is a strong signal but only a yes or no. Ranking findings in a production firmware image means weighing all of these at once, and weighing them differently depending on who is asking.
BRS is built around four goals:
* **Transparency.** Every metric, weight, and calculation step is visible and reproducible.
* **Configurable emphasis.** Profiles re-weight the taxonomy groups for different workflows; you select the profile that matches your task.
* **Data flexibility.** The score uses publicly available data where it exists and Binarly research data where it does not, and new metrics can be added without reworking the formula.
* **Finding-type coverage.** The same model prioritizes known CVEs, unknown UEFI vulnerabilities, secrets, mitigation failures, cryptographic weaknesses, malicious code, supply-chain issues, and hardening weaknesses.
## How the score is built
Each metric belongs to one of four taxonomy groups. Every group produces a weighted subscore, and the four subscores are blended into the final result.
| Group | What it measures |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Exploitation** | How likely and how easy the finding is to exploit. |
| **Impact** | How much damage exploitation would cause. |
| **Decision** | How confident and actionable the finding is: detection confidence, reachability confidence, fix availability, dispute status. |
| **Name** | A finding-type multiplier derived from the finding name itself. |
The **Name** group replaces the earlier "kind" concept. The finding name (for example `mitigation/uefi/untrusted-ami-test-key`) is matched against a table of prefixes by longest-prefix match, so `mitigation/uefi/untrusted-ami-test-key` resolves to its exact entry while an unlisted `mitigation/uefi/...` name falls back to the closest parent prefix. The matched value scales the score up or down for that class of finding. A few classes carry negative values, which pull the score down when the finding type is inherently low-risk.
## Scoring profiles
The platform ships three profiles. You select one from the Risk Score selector in the findings grid; the three share the same metrics and differ only in how much weight each taxonomy group carries. The alpha columns below are the group weights ($\alpha$) each profile applies.
| Profile | Exploitation | Impact | Decision | Name | Use it for |
| ------------------------------------- | :----------: | :----: | :------: | :--: | -------------------------------------------------- |
| **Balanced** | 0.25 | 0.25 | 0.25 | 0.25 | General assessment and baseline reviews. |
| **Exploitation (Exploitability)** | 0.55 | 0.20 | 0.20 | 0.05 | Threat hunting and active-exploitation triage. |
| **Decision Impact (Actionable Risk)** | 0.10 | 0.35 | 0.40 | 0.15 | Vulnerability management and remediation planning. |
The profiles were renamed for clarity: Exploitation is now Exploitability, and Decision Impact is now Actionable Risk. The findings grid shows the current names. Exploitation leans on the Exploitation group; Decision Impact leans on the Decision and Impact groups.
Profiles change only the ranking emphasis, not the underlying data. The same finding keeps all of its metric values across profiles, so switching profiles reorders findings rather than rescanning them.
### What a profile contains
A profile is a configuration with two parts:
* **Alphas** ($\alpha$): how much each taxonomy group contributes to the final score. The four alphas (exploitation, impact, decision, name) sum to 1.
* **Weights**: per finding category, how much each metric contributes inside its group. A weight is between 0 and 1, and a weight of 0 disables the metric for that category.
Within each finding category, the weights in a group are normalized so the group sums to 1: each metric's weight is divided by the total of its group. A group with a single metric and the alphas themselves are left unchanged.
![Normalized weight equals the raw weight divided by the sum of the group's weights when the group has more than one metric, and the raw weight otherwise.]()
This normalization runs once when the profile is built, so the scoring formula operates on already-normalized weights. The enumeration-to-number tables, the per-category recoverability factors, and the mapping of metrics to taxonomy groups are shared by every profile, not part of any single profile.
## The formula
The score is a weighted sum over the four groups, clamped to the range 0 to 1:
$$
\mathrm{BinarlyRiskScore} = \operatorname{clamp}_{[0,1]}\!\left( \sum_{g \in G} \alpha_g \cdot s_g \cdot \sum_{m \in g} v_m \cdot w_{g,m} \right)
$$
where, for each group $g$ in $G = \{\text{exploitation}, \text{impact}, \text{decision}, \text{name}\}$:
* $\alpha_g$ is the profile alpha for the group.
* $s_g$ is the redistribution scale for the group (defaults to 1, see [Weight redistribution](#weight-redistribution)).
* $v_m$ is the normalized value of metric $m$, in the range 0 to 1. A missing metric contributes 0.
* $w_{g,m}$ is the profile weight for metric $m$ in the group, already normalized per group (see [What a profile contains](#what-a-profile-contains)). A weight of 0 disables the metric for that finding category.
Because the weights in each group sum to 1 and the alphas sum to 1, and every metric value sits between 0 and 1, the result stays on a comparable 0 to 1 scale across findings and across images. The weights are normalized once when the profile is built, not per score.
![Binarly Risk Score equals the sum over taxonomy groups of the group alpha times the sum of each metric value times its weight, plus the Name group term.]()
### Metric normalization
Every metric is reduced to a value between 0 and 1 before it enters the formula:
* **Ratios** (CVSS base, CVSS exploitability, CVSS impact, EMS) are divided by 10. CVSS uses the highest of the available v2, v3, and v4 scores.
* **Probabilities** (EPSS, LEV, confidence, reachability confidence) are used directly.
* **Booleans** (KEV, public exploit, public PoC, verified exploit, weaponized exploit, SSVC Automatable, known fixed version, not disputed) map to 1 for true and 0 for false.
* **Enumerations** (severity, reachability kind, SSVC states, finding name) map to fixed values from the [appendix tables](#appendix).
A finding can have several reachability results. BRS selects the single entry with the highest `kind value * confidence` product, the most reachable path, and uses its kind and confidence. Environment reachability is selected the same way from its own set.
## Weight redistribution
Not every finding has a value for every metric, usually because the source data does not exist. Treating a missing metric as 0 would silently discard both the metric and its weight, dragging strong findings down for reasons that have nothing to do with risk.
Instead, the weight of a missing metric is partly redistributed to the metrics that do have values in the same group. Each metric has a recoverability factor between 0 and 1 that controls how much of its weight is donated when it is missing. A factor of 1 means the metric's signal is well represented by its neighbors, so its weight moves over in full; a factor of 0 means nothing is donated.
For a group $g$ and finding category $c$, the redistribution scale is:
$$
s_g = \frac{W_{\text{present}} + \displaystyle\sum_{m \,\in\, \text{missing}} w_{g,m} \cdot f_{c,m}}{W_{\text{present}}}, \qquad W_{\text{present}} = \sum_{m \,\in\, \text{present}} w_{g,m}
$$
where $f_{c,m}$ is the recoverability factor for metric $m$ in category $c$ (see [Redistribution factors](#redistribution-factors)). Because the donated weight is shared in proportion to the surviving weights, the whole group scales by one factor rather than rewriting each weight individually. When a group has no surviving metrics ($W_{\text{present}} = 0$), its scale is 1 and the group contributes 0.
## Reading the score
The result is a value between 0 and 1. The platform presents it as a percentile, so a finding scoring higher than most others appears at the top of the list. There are no fixed severity bands: you sort and filter on the score directly rather than mapping it to a label. You do this from the Risk Score column in the findings grid, covered in [Prioritizing with the Risk Score](/user-guides/image-scans/risk-score).
## Metrics reference
All metrics that can feed the score, grouped by taxonomy. Values are normalized to 0 to 1 as described above.
### Exploitation metrics
| Metric | Description | Source | Range |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------- | ------- |
| CVSS exploitability score | How easily the vulnerability can be exploited. Highest of CVSS v2/v3/v4. | NVD | 0 - 10 |
| EPSS | Probability the vulnerability will be exploited. Estimated EPSS is used for findings without a published EPSS score. | FIRST.org / Binarly | 0 - 1 |
| [EMS](/resource-center/ems-escalations) | Exploitation Maturity Score, evidence-based exploitation signal. | Binarly | 0 - 10 |
| KEV | Listed in the CISA Known Exploited Vulnerabilities catalog. | CISA | boolean |
| LEV | Likely Exploited Vulnerabilities probability, from historical exploitation data. | CISA / Binarly | 0 - 1 |
| Public exploit | A public exploit is known. | Binarly VDB | boolean |
| Public PoC | A public proof of concept is known. | Binarly VDB | boolean |
| Verified exploit | A verified exploit is known. | Binarly VDB | boolean |
| Weaponized exploit | A weaponized exploit is known. | Binarly VDB | boolean |
| [Reachability kind](/resource-center/asap) | Static reachability classification of the vulnerable code. | Binarly | enum |
| Brly rule | The finding was raised by a Binarly research rule. | Binarly | boolean |
| Secret exploitation | The secret was validated (a secret finding at full confidence). | Binarly | boolean |
| SSVC Automatable | SSVC automatable assessment. | CISA | boolean |
| SSVC Exploitation | SSVC exploitation state. | CISA | enum |
### Impact metrics
| Metric | Description | Source | Range |
| ----------------------------------------- | ------------------------------------------------ | ------- | ------ |
| CVSS base score | Overall CVSS severity. Highest of CVSS v2/v3/v4. | NVD | 0 - 10 |
| CVSS impact score | CVSS impact subscore. | NVD | 0 - 10 |
| [Severity](/resource-center/risk-scoring) | Binarly severity level of the finding. | Binarly | enum |
| SSVC Technical Impact | SSVC technical impact level. | CISA | enum |
### Decision metrics
| Metric | Description | Source | Range |
| -------------------------------------------------- | ---------------------------------------------------------- | ----------- | ------- |
| [Confidence](/resource-center/accuracy-confidence) | Detection confidence for the finding. | Binarly | 0 - 1 |
| Known fixed version | A fixed version is available. | Binarly VDB | boolean |
| Not disputed | The CVE is not disputed. | NVD | boolean |
| [Reachability confidence](/resource-center/asap) | Confidence in the reachability analysis. | Binarly | 0 - 1 |
| SSVC Paranoid Decision | Binarly's SSVC-style decision, biased toward action. | Binarly | enum |
| Environment reachability kind | Reachability of the finding in its deployment environment. | Binarly | enum |
| Environment reachability confidence | Confidence in the environment reachability analysis. | Binarly | 0 - 1 |
### Name metric
| Metric | Description | Source | Range |
| ------ | ----------------------------------------------------------------------- | ------- | -------- |
| Name | Finding-type multiplier from the finding name, by longest-prefix match. | Binarly | -0.3 - 1 |
## Metrics by finding type
The metrics the shipped profiles weight for each finding type, grouped by taxonomy.
![Heatmap showing which metrics each finding type weights, colored by taxonomy group: exploitation, impact, decision, and name.]()
| Finding type | Exploitation | Impact | Decision |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Known vulnerability** | EPSS, CVSS exploitability, EMS, KEV, LEV, reachability kind, public exploit, public PoC, verified exploit, weaponized exploit, SSVC Automatable, SSVC Exploitation | CVSS base, CVSS impact, SSVC Technical Impact | Confidence, known fixed version, not disputed, SSVC Paranoid Decision, reachability confidence, environment reachability |
| **Unknown vulnerability (UEFI)** | EPSS, CVSS exploitability, reachability kind | CVSS base, CVSS impact, severity | Confidence, reachability confidence, environment reachability |
| **Mitigation failure** | EPSS, CVSS exploitability, EMS, KEV, LEV, reachability kind | CVSS base, severity | Confidence, reachability confidence, environment reachability |
| **Cryptographic material** | EPSS, CVSS exploitability | CVSS base, CVSS impact, severity | Confidence, environment reachability |
| **Secret** | Secret exploitation | Severity | Confidence |
| **Malicious code** | Brly rule, reachability kind | Severity | Confidence, reachability confidence, environment reachability |
| **Supply-chain failure** | Reachability kind | Severity | Confidence, reachability confidence, environment reachability |
| **Suspicious code** | Brly rule | Severity | Confidence, environment reachability |
| **Weakness** | - | Severity | Confidence, environment reachability |
All finding types also carry the **Name** multiplier. A metric appearing here does not mean it is set for every finding: it means at least one shipped profile assigns it a weight. Metrics with no data for a given finding are handled by [weight redistribution](#weight-redistribution).
## Examples
The same findings reorder under each profile without rescanning. In the platform you switch profiles from the Risk Score selector in the findings grid. The diagrams below show the weight configuration behind each shipped profile.
### Balanced
Equal emphasis across all four groups. This produces a general-purpose ranking that no single factor dominates, which suits baseline reviews.
![Balanced profile weight configuration.]()
### Exploitation (Exploitability)
The Exploitation group carries 55 percent of the score. Findings with high EPSS and EMS, a KEV listing, or a known public exploit rise to the top, which suits incident response and threat hunting.
![Exploitation (Exploitability) profile weight configuration.]()
### Decision Impact (Actionable Risk)
The Decision and Impact groups together carry 75 percent of the score. Findings with high detection confidence, available reachability data, and high impact rise to the top, which suits vulnerability management and remediation planning.
![Decision Impact (Actionable Risk) profile weight configuration.]()
## Appendix
### Enumeration values
String metrics map to fixed numeric values before scoring.
| Metric | Value | Score |
| --------------------------------- | ------------------ | :---: |
| **Severity** | Critical | 1 |
| | High | 0.85 |
| | Medium | 0.5 |
| | Low | 0.3 |
| | Unspecified | 0 |
| **Reachability kind** | Entrypoint | 1 |
| | Exported | 0.8 |
| | Referenced | 0.5 |
| | Undetermined | 0.2 |
| | Unreachable | 0.01 |
| **Environment reachability kind** | Entrypoint | 1 |
| | Runtime dependency | 0.8 |
| | Runtime invocation | 0.8 |
| | Undetermined | 0.1 |
| **SSVC Exploitation** | Active | 1 |
| | PoC | 0.6 |
| | None | 0.1 |
| **SSVC Technical Impact** | Total | 1 |
| | Partial | 0.5 |
| **SSVC Paranoid Decision** | Act | 1 |
| | Attend | 0.7 |
| | Track Star | 0.5 |
| | Track | 0.3 |
### Finding name multipliers
The Name group value for each finding-name prefix. Unlisted names fall back to their closest parent prefix.
| Finding type | Name prefix | Value |
| -------------------------- | ---------------------------------------------------- | :---: |
| **Cryptographic material** | `crypto/algorithm/` | -0.3 |
| | `crypto/certificate/` | 0.1 |
| | `crypto/certificate/expired` | 0.9 |
| | `crypto/certificate/invalid` | 0.9 |
| | `crypto/certificate/untrusted` | 0.9 |
| | `crypto/protocol/` | -0.3 |
| | `crypto/rsa/weak-key-parameters` | 0.9 |
| **Known vulnerability** | `vulnerability/known-vulnerability` | 1 |
| **Malicious code** | `malware/known-threat` | 1 |
| | `malware/malicious-behaviour` | 0.9 |
| | `malware/uefi/implant-hook-install` | 0.8 |
| **Mitigation failure** | `mitigation/known-mitigation-failure` | 0.75 |
| | `mitigation/missing-control-flow-integrity` | 0.3 |
| | `mitigation/missing-stack-canaries` | 0.3 |
| | `mitigation/posix/fortify-source-disabled` | 0.1 |
| | `mitigation/posix/nx-disabled` | 0.35 |
| | `mitigation/posix/pie-disabled` | 0.35 |
| | `mitigation/posix/relro-disabled` | 0.4 |
| | `mitigation/posix/relro-partially-enabled` | 0.4 |
| | `mitigation/uefi/dxe/stack-guard-misconfiguration` | 0.4 |
| | `mitigation/uefi/flash-descriptor-misconfiguration` | 1 |
| | `mitigation/uefi/insyde-fdm-misconfiguration` | 1 |
| | `mitigation/uefi/leaked-ami-test-key` | 1 |
| | `mitigation/uefi/memory-protection-misconfiguration` | 0.4 |
| | `mitigation/uefi/missing-rsb-stuffing` | 0.4 |
| | `mitigation/uefi/outdated-amd-microcode-version` | 0.55 |
| | `mitigation/uefi/outdated-dbx` | 0.5 |
| | `mitigation/uefi/outdated-intel-microcode-version` | 0.65 |
| | `mitigation/uefi/outdated-microcode-version` | 0.65 |
| | `mitigation/uefi/pei/stack-guard-misconfiguration` | 0.5 |
| | `mitigation/uefi/secure-boot-setup-mode` | 1 |
| | `mitigation/uefi/uefi-shell-inclusion` | 1 |
| | `mitigation/uefi/uefiplat-weak-configuration` | 0.85 |
| | `mitigation/uefi/untrusted-ami-test-key` | 1 |
| | `mitigation/uefi/untrusted-insyde-test-key` | 1 |
| | `mitigation/uefi/untrusted-phoenix-test-key` | 1 |
| | `mitigation/uefi/vulnerable-amd-microcode-version` | 1 |
| | `mitigation/uefi/vulnerable-intel-microcode-version` | 1 |
| **Secret** | `secret/api-credentials` | 1 |
| | `secret/credentials` | 1 |
| | `secret/encryption-key` | 1 |
| | `secret/generic` | 1 |
| | `secret/jwt-token` | 1 |
| | `secret/oauth-credentials` | 1 |
| | `secret/private-key` | 1 |
| | `secret/webhook-url` | 1 |
| **Supply-chain failure** | `supply-chain/known-supply-chain-issue` | 1 |
| **Suspicious code** | `suspicious/posix/ctors-dtors` | 0.4 |
| | `suspicious/posix/dt-needed` | 0.4 |
| | `suspicious/posix/entrypoint` | 0.4 |
| | `suspicious/posix/executable-data` | 0.4 |
| | `suspicious/posix/ifuncs` | 1 |
| | `suspicious/posix/init-fini` | 0.4 |
| | `suspicious/posix/no-stdlib` | 0.4 |
| | `suspicious/posix/packed-elf` | 0.4 |
| | `suspicious/posix/plt-got` | 0.4 |
| | `suspicious/posix/pt-note-conversion` | 0.4 |
| | `suspicious/posix/relocations` | 0.4 |
| | `suspicious/posix/reverse-text` | 0.4 |
| | `suspicious/posix/text-padding` | 0.4 |
| | `suspicious/uefi/resolve-imports` | 0.3 |
| | `suspicious/uefi/resolve-relocations` | 0.3 |
| **Unknown vulnerability** | `vulnerability/uefi/` | 0.2 |
| | `vulnerability/uefi/get-set-variable` | 0.2 |
| | `vulnerability/uefi/leaked-boot-guard-bpm-key` | 1 |
| | `vulnerability/uefi/leaked-boot-guard-km-key` | 1 |
| | `vulnerability/uefi/pkfail` | 0.9 |
| | `vulnerability/uefi/secure-boot-bypass` | 1 |
| | `vulnerability/uefi/smm-get-set-variable` | 0.2 |
| **Weakness** | `weakness/linux/kernel-configuration` | 0.8 |
| | `weakness/posix/not-stripped` | 0.25 |
| | `weakness/posix/rpath-set` | 0.6 |
| | `weakness/posix/runpath-set` | 0.6 |
| | `weakness/posix/unsafe-function-call` | 0.8 |
| | `weakness/posix/unsafe-functions/summary` | 0.25 |
### Redistribution factors
The recoverability factor $f_{c,m}$ for each metric, by finding category. Higher values donate more of a missing metric's weight to its surviving neighbors.
| Category | Metric | Factor |
| -------------------------------- | ------------------------- | :----: |
| **Cryptographic material** | confidence | 0 |
| | CVSS base score | 1 |
| | CVSS exploitability score | 1 |
| | CVSS impact score | 1 |
| | EPSS probability | 1 |
| | is untrusted key | 1 |
| | name | 0 |
| | reachability confidence | 0 |
| | reachability kind | 0 |
| | severity | 0 |
| **Malicious code** | brly rule | 1 |
| | confidence | 0 |
| | name | 0 |
| | reachability confidence | 0 |
| | reachability kind | 0 |
| | severity | 0 |
| **Mitigation failure** | brly rule | 1 |
| | confidence | 0.9 |
| | CVSS base score | 1 |
| | CVSS exploitability score | 0.9 |
| | CVSS impact score | 1 |
| | EMS score | 1 |
| | EPSS probability | 0.8 |
| | is untrusted key | 1 |
| | KEV | 1 |
| | LEV score | 1 |
| | name | 1 |
| | reachability confidence | 1 |
| | reachability kind | 1 |
| | severity | 0.8 |
| **Secret** | confidence | 0 |
| | name | 0 |
| | secret exploitation | 0 |
| | severity | 0 |
| **Supply-chain failure** | brly rule | 0.2 |
| | confidence | 0 |
| | name | 0 |
| | reachability confidence | 0.7 |
| | reachability kind | 0.7 |
| | severity | 0 |
| **Suspicious code** | confidence | 0 |
| | name | 0 |
| | severity | 0 |
| **Known vulnerability** | brly rule | 0.4 |
| | confidence | 0 |
| | CVSS base score | 0.7 |
| | CVSS exploitability score | 0.8 |
| | CVSS impact score | 0.8 |
| | EMS score | 0.6 |
| | EPSS probability | 0 |
| | KEV | 1 |
| | is known ransomware use | 0.8 |
| | known fixed version | 1 |
| | LEV score | 1 |
| | not disputed | 1 |
| | public exploit | 1 |
| | public PoC | 1 |
| | verified exploit | 1 |
| | weaponized exploit | 1 |
| | reachability confidence | 0 |
| | reachability kind | 0 |
| | severity | 0 |
| | SSVC Automatable | 0.9 |
| | SSVC Exploitation | 0.9 |
| | SSVC Paranoid Decision | 0.7 |
| | SSVC Technical Impact | 0.9 |
| **Unknown vulnerability (UEFI)** | confidence | 0.7 |
| | CVSS base score | 1 |
| | CVSS exploitability score | 1 |
| | CVSS impact score | 1 |
| | EPSS probability | 0.5 |
| | name | 0.7 |
| | reachability confidence | 1 |
| | reachability kind | 1 |
| | severity | 0 |
| **Weakness** | confidence | 0 |
| | name | 0 |
| | severity | 0 |
## Related
Pick a profile and sort and filter findings by risk score in the findings grid.
How reachability feeds the exploitation and decision groups.
The evidence-based exploitation signal in the score.
How detection confidence, a decision-group input, is set.
# Code Size Limit
Source: https://docs.binarly.io/resource-center/code-size-limit
How the code size limit decides which binary components the Binarly Analysis Engine analyses, and where components excluded from analysis are reported.
The Binarly Analysis Engine caps how much code a single binary component may contain before analysis skips it. A component over the cap is still unpacked and listed with its name and path, but its code is not analysed, so no code-derived findings are produced for it.
Memory and scan time depend on the size of the individual components in an image. The limit is therefore a tested value set per deployment, not a fixed platform constant, and it can be reviewed for your workload.
## What code size means
Code size is the amount of executable code in a component as it would be loaded into memory. It is not the file size on disk, and it does not include data sections.
| Format | Code size is |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| ELF | The sum of the memory sizes of all executable program headers. When a binary has none, the allocated executable sections are summed instead. |
| PE | The sum of the virtual sizes of all sections marked as code or executable. |
| TE (UEFI terse executable) | The sum of the virtual sizes of all sections marked as code or executable. |
A component with no executable sections has a code size of zero and is never excluded, however large the file is.
The limit applies only to components the platform classifies as binary code. Components on non-binary platforms are analysed regardless of size.
## What happens to an excluded component
The component keeps its place in the scan results. What changes is analysis coverage:
* Analysis tools that hit the limit skip the component and produce no findings from its code.
* The scan records a `metadata/analysis/exceeds-code-size-limit` property against the component, carrying its actual code size and the limit it exceeded. See [Metadata Classes](/resource-center/finding-classes#metadata-classes) for where this class sits.
* The component still appears in the component tree with its name and path.
Coverage is reduced rather than absent, because the limit can be configured per analysis tool. A component can be over one tool's limit and under another's, in which case the tools with the higher limit still analyse it.
## Finding excluded components
In the platform UI, the Components tab on an image carries the configured limit in its tooltip, and its **Reduced analysis coverage** tab lists every component that was skipped, with a count next to the tab label. Each row shows the component name, its code size, its path, and the reason it was excluded. Name and path filter on substrings, and code size sorts. When nothing was skipped the tab is empty and disabled. The upload dialog states the limit before you submit a file. See [Components tab](/user-guides/image-scans/all-about-details#components-tab) for the walkthrough.
The tooltip and the upload notice state the limit from your instance configuration. The Reason column on each row shows the limit that component was measured against, which can be lower where an individual analysis tool is configured differently.
The same list is available from the components grid endpoint by filtering on the exclusion reason:
```bash theme={null}
curl -s -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"filters": [
{"field": "productId", "value": "'"$BINARLY_PRODUCT_ID"'", "comparator": "equals"},
{"field": "imageId", "value": "'"$IMAGE_ID"'", "comparator": "equals"},
{"field": "reason", "value": ["exceedsCodeSizeLimit"], "comparator": "in"}
]
}' \
"${BINARLY_API_URL}/api/v4/grids/components:gridList"
```
Each returned row carries `codeSize` and `codeSizeLimit` in bytes alongside `reason`. All three are absent for components that were analysed in full.
## If you need more coverage
Binarly sets the limit to a tested value that keeps scans within the resourcing an instance is provisioned for. If components you care about show up under Reduced analysis coverage and you need them analysed, contact [Binarly Support](/user-guides/about/customer-support) with the image and the components in question, and we will review the limit for your workload.
Self-hosted operators set the value themselves. See [Analysis Code Size Limit](/on-prem/v3/considerations#analysis-code-size-limit) for the chart value, the default, and the resourcing to account for before raising it.
## Related
* [Components tab](/user-guides/image-scans/all-about-details#components-tab) - Reviewing components and reduced analysis coverage in the UI
* [Finding Classes Reference](/resource-center/finding-classes#metadata-classes) - Where the code size limit metadata class sits
* [Analysis Code Size Limit](/on-prem/v3/considerations#analysis-code-size-limit) - Setting the limit in a self-hosted deployment
* [Component and Version Identification](/resource-center/component-identification) - How components are identified before any code analysis runs
# Component and Version Identification
Source: https://docs.binarly.io/resource-center/component-identification
How the Binarly Transparency Platform identifies third-party components and their versions inside a binary, using package metadata, content rules, filename signals, and code similarity.
The Binarly Transparency Platform (BTP) identifies third-party components from evidence found in the scanned image: the contents of the binaries themselves, and the package databases the image happens to carry. A component is recognized because that evidence is present, whether or not a supplied SBOM, build manifest, or attestation declared it.
Identified components appear in the [Components tab](/user-guides/image-scans/all-about-details), populate the [binary-derived SBOM](/user-guides/export/sbom), and provide the product and version data that known-vulnerability matching runs against.
## Identification signals
Four signals contribute, and they establish different things.
| Signal | What it establishes |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Strings recovered from the binary | That the component is present, and which version it is |
| The component filename | That the component is present, and that this file *is* the component rather than merely containing it |
| Package manager metadata | That the component is present, and its exact version, without inferring either from binary contents |
| Code similarity to reference builds | That the component is present, when no version string survives in the binary |
Only two of these produce a version. Package metadata supplies one directly, and recovered strings are how a version is read out of the binary itself. A filename match identifies a component without producing a version, and so does a code-similarity match. This distinction drives most of the behavior described below.
The signals are not alternatives. On an image that carries a package database, all four run, and the platform has to decide which one to trust for a given component. That decision is covered in [When package data takes precedence](#when-package-data-takes-precedence).
## Rule-based identification
Rule-based identification covers native and embedded targets: Linux and POSIX ELF binaries, Linux kernel images, U-Boot, and Zephyr or MCUboot images. These targets are marked **Known (version)** in the [analysis capability matrix](/user-guides/about/supported-platforms#analysis-capability-matrix). Packages from language ecosystems are identified from their own manifests rather than by the rules described here, and are not covered on this page.
BTP maintains a library of component rules covering widely used open-source software: cryptographic and TLS libraries, compression, networking and server software, core Linux userland, media codecs, parsers, databases, language runtimes, and embedded and industrial components. The set grows with each release.
A rule matches on the strings recovered from a component, on the component's filename, or on both, and separately captures the version out of the recovered text. Each rule carries one or more vendor and product identities, which key the [vulnerability database](/resource-center/vdb-sources) lookup and become the CPE recorded against the component in scan output and exports.
### What the filename contributes
The filename is a real signal, but a narrow one.
Filename matching uses the **basename only**. The directory a component was unpacked into is not used as an identity signal, so the same binary is identified the same way regardless of where it sits in the extracted tree.
Build paths do still contribute, but as recovered strings rather than as path signals. A compiler that bakes `bzip2-1.0.8/blocksort.c` into a binary has put that path into the string table, where a rule can match it. That is a property of the file's contents, not of its location on disk.
A filename match alone never yields a version. If a rule identifies a component by name but no version is recovered from the strings, the component is reported without one. Renamed, stripped, or heavily size-optimized builds land in this case routinely.
### How linkage is determined
Every identified component is recorded with a [dependency linkage](/resource-center/transitive-dependencies) describing its relationship to the file it was found in. The signal that matched decides it.
A **filename** match means the file *is* the component, so the result is recorded as **Project**.
A **content** match means the file *contains* the component, and the linkage comes from the rule:
| Declared linkage | When a rule uses it |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Embedded | Libraries that are commonly linked into a larger binary. This is the common case. |
| Project | Multi-binary suites, where any one applet belongs to the parent project. |
| Build | Toolchain and build-provenance artifacts, where the match records what built the binary rather than what ships inside it. |
A Project result is reclassified to **Vendored** when [package metadata](#package-metadata-identification) disagrees with the identified product, meaning the component ships inside a package that is not its own.
## Package metadata identification
Where an image carries a package database, the platform reads it. This is the most precise identification available, because the package manager already recorded exactly what was installed and at which version, and no inference from binary contents is required. The databases maintained by dpkg, rpm, and apk are supported, along with standalone rpm packages found in an image. Which of them is read depends on the image type, listed under [Package manager coverage](/resource-center/provenance#package-manager-coverage).
Each package record contributes its name, version, architecture, source package, vendor, and license. The source package matters as much as the name, because advisories are frequently filed against the source rather than the binary package, so a component installed as `libssl3` is still matched against advisories for `openssl`.
A package database also records which files each package owns, which lets the platform attribute a component to its package. This is what identifies a binary that carries no version string at all: a stripped, size-optimized library that no rule can version is still reported with an exact version when its package owns it.
### Operating system and ecosystem detection
The platform reads the image's operating system release metadata and normalizes it into an ecosystem identifier that names the distribution and its release. Alpine, CentOS, Debian, Red Hat Enterprise Linux, Rocky Linux, and Ubuntu are recognized.
The ecosystem is what connects a component to the right advisory stream. Ubuntu Security Notices apply to an Ubuntu image, Red Hat and Rocky advisories to their respective images, and so on. Without it, only upstream version ranges are available.
An image containing several root filesystems can yield more than one ecosystem. In that case the platform records the candidates rather than committing to one.
### When package data takes precedence
Package data and binary-level identification can both describe the same component, so the platform picks one as authoritative rather than reporting both.
Three conditions must hold together for package data to win: the component must be the package itself rather than something vendored inside it, package metadata must be present, and the vulnerability database must carry advisory coverage for the detected ecosystem.
| Situation | Vulnerability matching |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| The component is its package, and the ecosystem has advisory coverage | Package data is authoritative. Version-based matching is skipped for that component. |
| The component is its package, but the ecosystem has no advisory coverage | Falls back to version-based matching. An empty advisory result proves nothing here. |
| The component is a vendored copy inside another package | Version-based matching. A vendored copy is not fixed by the distribution's patches. |
| The component is statically linked, or no package owns it | Version-based matching. |
Skipping the version-based query is deliberate. Matching a distribution's package against upstream version ranges reports vulnerabilities the distribution has already fixed, so where a distribution's own advisories are available they replace that query instead of supplementing it.
Findings record which path produced them, and package-derived findings carry higher [confidence](#confidence) than version-derived ones.
Identification is reported either way. A component that a distribution has patched still appears in the SBOM with its package, version, and license, carrying no findings.
![Three columns comparing a proprietary custom OS built from scratch, a public OS fork with no package data, and a standard Linux distribution image. Each column lists what the image provides, how components are identified, version quality, vulnerability matching, and finding confidence, which rises from lower to medium to higher across the three. A band across the bottom states that binary-level identification and VulHunt rules run in all three cases, finding statically linked and vendored components that no package database declares and catching backported fixes that version matching would report as vulnerable.]()
Package data raises precision where it exists. It does not replace binary-level identification, which runs in every case and is the only thing that finds statically linked and vendored components, because a package database records what the distribution installed and never what was compiled into it.
### How backported patches are resolved
A distribution that backports a fix leaves the upstream version number unchanged, so upstream version ranges still mark the package vulnerable. Two mechanisms correct this, and they apply in different situations.
Where package data and advisory coverage are both available, the distribution's own advisories record the fix against the distribution's package version, and matching against those advisories resolves the CVE correctly. The fixed version reported back is the distribution's, not upstream's. This depends on having the package version, which only the package database supplies, so recognizing that an image is Ubuntu 22.04 is not sufficient on its own.
Where they are not, [VulHunt](https://vulhunt-docs.binarly.io/user-guide/get-started/introduction) covers part of the gap. VulHunt reasons about what a component's code actually does rather than what version it claims to be, so a backported fix is visible to it even though the version string is unchanged. These are the **Known (code)** findings in the [analysis capability matrix](/user-guides/about/supported-platforms#analysis-capability-matrix). Coverage extends to the vulnerabilities that have a rule, which narrows the problem rather than removing it.
![Two version tracks. Upstream goes from 3.0.2, which carries the vulnerability, to 3.0.14, where the fix is released. A dashed arrow shows the fix being backported onto the 3.0.2 base, producing Ubuntu 22.04 package 3.0.2-0ubuntu1.15, which is patched but still reads 3.0.2. Below, three sources give their verdict: an upstream version range says vulnerable, which is the false positive, while the distribution advisory and VulHunt both say fixed.]()
## Hybrid identification for UEFI components
UEFI firmware modules rarely carry the version banners that userland binaries do, and third-party code in firmware is statically linked into modules that were never packaged separately. Identification for selected UEFI components therefore combines version-string search with code similarity against reference builds of the component.
The version-string branch runs first. Code similarity runs only where that branch does not match, so a firmware image carrying a plain version banner is identified from the banner and never invokes the similarity path.
Version strings give both identity and version. Code similarity gives identity only. Where similarity is the sole evidence, the reported version is a range asserted by the rule, or unknown.
Similarity coverage is targeted rather than exhaustive. It focuses on the third-party code most often found statically linked in firmware: cryptographic and TLS libraries, compression, image parsing, network supplicants, TPM and TCM drivers, and OEM and silicon vendor reference code. Coverage grows with each release.
Third-party code identified in a UEFI module is always recorded as **Embedded**, since a library inside a firmware module is statically linked by definition.
## Confidence
The confidence on a finding reflects which signal produced it.
Findings matched from a distribution's advisories, where package data was authoritative, are the most reliable of the three paths. Findings matched from a version recovered from the binary are less so, and lower again where the component was identified as contained in the scanned file rather than as the file itself, since the version then describes something embedded rather than the file being reported.
Confidence in the identification and confidence in the vulnerabilities inferred from it are recorded separately, because strong evidence that a component is present is not automatically strong evidence about its version. Both map onto the scale described in [Accuracy & Confidence in Findings](/resource-center/accuracy-confidence).
## Limitations
Where neither package data nor a VulHunt rule applies, a version number is all there is to match against, and a vendor that backports a fix without changing that version leaves the component looking vulnerable when it is not. Version matching on its own cannot distinguish a patched build from an unpatched one at the same version. See [How backported patches are resolved](#how-backported-patches-are-resolved) for the cases that are covered.
Package database coverage differs by image type, as set out in [Package manager coverage](/resource-center/provenance#package-manager-coverage). A Debian or Alpine based firmware image falls outside it and is identified from binary contents alone.
Components identified only by code similarity carry a version range or no version at all, which limits how precisely vulnerabilities can be matched to them.
Stripped, renamed, or rebranded builds that retain no version strings and belong to no package are identified without a version. Aggressive size optimization that discards usage text and banners has the same effect.
Obfuscated components, and forks modified far enough from their upstream, may no longer resemble the reference builds closely enough to be identified.
Rule coverage is finite. A component with no rule, no similarity reference, and no owning package is not identified, even when it is present.
## Related
* [Transitive Dependencies](/resource-center/transitive-dependencies) - The eight dependency linkage types and what each one means
* [Vulnerability Data Sources](/resource-center/vdb-sources) - The data the vendor and product identities are matched against
* [Accuracy & Confidence in Findings](/resource-center/accuracy-confidence) - The confidence scale identification and finding confidence map onto
* [Supported Platforms](/user-guides/about/supported-platforms) - Which targets support version-based identification
* [SBOM Export](/user-guides/export/sbom) - Exporting the identified component inventory
* [VulHunt](https://vulhunt-docs.binarly.io/user-guide/get-started/introduction) - Semantic rule-based detection, which finds vulnerabilities in code regardless of the version a component reports
# Cryptographic Detection
Source: https://docs.binarly.io/resource-center/cryptographic-detection
How the Binarly Transparency Platform detects cryptographic materials in firmware and binary images.
The Binarly Transparency Platform (BTP) statically analyzes binary images to detect cryptographic materials - algorithms, protocols, certificates, and keys - without requiring source code or debug information. Detected properties appear in the [Cryptographic Materials tab](/user-guides/image-scans/cryptographic-materials) and are exported in the [CBOM](/user-guides/export/cbom) and [PQC Compliance Report](/user-guides/export/pqc).
## Detection by Binary Type
### Native Binaries
For native compiled binaries - UEFI firmware modules or ELF executables and libraries - detection is **code-based**.
BTP identifies cryptographic algorithm implementations by matching known algorithm-specific constants in code and data sections, tracing cross-references to those constants, and - for select algorithms - applying partial emulation to resolve indirect calls. Detection does **not** rely on symbol names, function names, or debug information:
* Custom implementations of well-known algorithms are still detected if the underlying code patterns are present.
* Stripped binaries are fully supported.
* Obfuscated or heavily modified implementations may reduce detection confidence or prevent detection entirely.
### Managed Runtimes
For binaries targeting managed runtimes - Java bytecode and Python packages - detection is **API-based**.
BTP identifies cryptographic usage by recognizing calls to supported cryptographic library APIs:
**Java:** [Apache Commons Codec](https://commons.apache.org/proper/commons-codec/), [Bouncy Castle](https://www.bouncycastle.org/), [Google Guava](https://github.com/google/guava), [Google Tink](https://developers.google.com/tink), JDK (`javax.crypto`, `java.security`)
**Python:** [`cryptography`](https://cryptography.io/), [M2Crypto](https://github.com/mcepl/M2Crypto), [Pooch](https://github.com/fatiando/pooch), [PyCryptodome](https://pycryptodome.readthedocs.io/), [PyNaCl](https://pynacl.readthedocs.io/), [pyOpenSSL](https://pyopenssl.org/), stdlib ([`hashlib`](https://docs.python.org/3/library/hashlib.html), [`hmac`](https://docs.python.org/3/library/hmac.html))
Custom algorithm implementations that bypass supported APIs will **not** be detected.
## Coverage by binary type
The set of detectable algorithms differs between binary types. Native code-based detection has the broadest coverage. API-based detection for managed runtimes is constrained to what the supported libraries expose.
| Category | Native | Java | Python |
| ---------------------------------- | ---------------------- | -------------- | -------------------------------------------- |
| Encryption | Full | Most ciphers | Common ciphers |
| Hashing — cryptographic | Full | Full | Full |
| Hashing — non-cryptographic | DJB2, FNV, MurmurHash3 | — | — |
| MAC | Full | Full | Full |
| Signing | Full | All except PQC | Common variants; no PQC, Ed25519, Ed448, SM2 |
| PQC signing (ML-DSA, SLH-DSA, LMS) | ✓ | — | — |
| PRNG (Mersenne Twister) | ✓ | — | — |
Non-cryptographic hashes, PRNG, and PQC signing are detected via code patterns in native binaries. These algorithms have no equivalent API surface in the supported Java or Python libraries.
## What Is Detected
### Algorithms and Protocols
Algorithm findings record the algorithm class, the binary component and offset where the implementation was found, and reachability information.
Algorithm classes follow the `crypto/algorithm/*` and `crypto/protocol/*` naming scheme. Detection coverage varies by binary type: native binaries use code-based detection, while managed runtimes (Java, Python) use API-based detection against supported libraries. See [Finding Classes Reference](/resource-center/finding-classes) for the full list.
### Certificates
Certificate findings record the full set of X.509 parameters: issuer, subject, validity period (not-before and not-after dates), expiration status, signature algorithm, public key algorithm and size, and whether the certificate is self-signed.
Certificate issue classes follow the `crypto/certificate/*` naming scheme. Certificates without issues are recorded as `artefact/crypto-certificate-material` properties.
### Keys
Key material records key type (RSA, EC, Ed25519, post-quantum), key size or parameter set, public vs. private classification, and location within the image.
Key material is recorded under `artefact/crypto-key-material`. Private keys exposed within firmware are additionally flagged under `secret/private-key` or `secret/encryption-key`.
For public RSA keys, BTP runs additional security checks and factorization attacks to identify weak or compromised keys:
| Check / Attack | Description | Kind |
| -------------------------- | --------------------------------------------------------------- | ------ |
| SizeCheck | Key is smaller than 2048 bits | Check |
| ExponentCheck | Public exponent is non-standard | Check |
| RocaCheck | Key is affected by the ROCA vulnerability | Check |
| RocaVariantCheck | Key is affected by a ROCA variant (any base) | Check |
| KeypairCheck | Key is affected by CVE-2021-41117 (Keypair factorization) | Check |
| FermatCheck | Key is factorable via Fermat's method | Attack |
| PollardPm1Check | Key may be vulnerable to Pollard's p−1 method | Attack |
| ContinuedFractionsCheck | Key has a large coefficient in its continued fraction expansion | Attack |
| BitPatternsCheck | Key contains a repeating bit pattern | Attack |
| PermutedBitPatternsCheck | Key contains a repeating permuted bit pattern | Attack |
| HighAndLowBitsEqualCheck | Enough bits in p and q coincide to allow factorization | Attack |
| LowHammingWeightCheck | Key is a product of low Hamming weight primes | Attack |
| SmallUpperDifferencesCheck | abs(p − q) has a special form enabling factorization | Attack |
| UnseededRandCheck | Key was generated from an unseeded random number generator | Attack |
## Confidence
Each cryptographic finding carries a confidence score reflecting how well the detected code pattern matched the algorithm. Confidence applies to algorithms, protocols, and assets (certificates and keys). See [Accuracy & Confidence in Findings](/resource-center/accuracy-confidence) for the full confidence model.
## Reachability
Reachability analysis determines whether a cryptographic implementation is accessible from a public entry point in the binary. A reachable finding indicates the implementation can be reached through an execution path, increasing the practical risk of weak or deprecated algorithm usage. See [Reachability Analysis](/resource-center/asap).
## Algorithm Compliance
Detected algorithms are evaluated against published security standards to identify weak, deprecated, or quantum-vulnerable implementations. See [Algorithm Compliance Reference](/resource-center/algorithm-compliance) for the full classification table.
## Limitations
Java and Python binaries using custom cryptographic implementations that bypass supported APIs will not be detected.
For obfuscated components, the analysis may be inaccurate and provide incorrect results or no results.
## Related
* [Cryptographic Materials Tab](/user-guides/image-scans/cryptographic-materials)
* [Algorithm Compliance Reference](/resource-center/algorithm-compliance)
* [Finding Classes Reference](/resource-center/finding-classes)
* [Accuracy & Confidence in Findings](/resource-center/accuracy-confidence)
* [Reachability Analysis](/resource-center/asap)
* [CBOM Export](/user-guides/export/cbom)
* [PQC Compliance Report](/user-guides/export/pqc)
# Debugging Symbols
Source: https://docs.binarly.io/resource-center/debugging-symbols
The Binarly Transparency Platform does not require source code access and instead works directly on the binary. Once it detects a vulnerable or dangerous code pattern it will include the decompiled representation of the affected function in the finding evidence. This decompiled code will likely differ from the source, simply because function and variable names as well as comments and type information are discarded at compile time.
To ease mapping findings back to the original source code, the Binarly Transparency Platform can utilize debugging symbols to include the correct function names.
# Applying Debug Information
Debugging symbols are metadata embedded in or associated with compiled binaries that include some of the information that is discarded during compilation, including original function names. BTP supports loading embedded DWARF for Linux-based images as well as separate PDB symbol files for UEFI binaries. The latter need to be uploaded to the image using the symbol upload button on the image dashboard shown below.
![PDB upload button on the overview tab.]()
![Select a PDB file and press Upload.]()
The PDB file is verified to include information for the image and then applied. To ensure the new information is used, issue a rescan of the binary using the Rescan Button (shown below).
![The rescan button is in the context menu on the image dashboard.]()
# Use Debug Information
Once the scan is finished, findings that include decompiled code snippets in their evidence will show the original function names if it's included in the uploaded PDB file like in the example below.
![Evidence with auto generated function name.]()
![Evidence with original function name.]()
## Programmatic Access
Upload debug symbols programmatically using the Binarly API:
* [Upload Debug Symbols API](/api-reference/file/create-file-attachment) - Endpoint reference and batch upload examples
# EMS Escalations: Exploitation Maturity Score scale and triggers
Source: https://docs.binarly.io/resource-center/ems-escalations
Learn how the Exploitation Maturity Score (EMS) rates vulnerabilities on a 0-10 scale, when escalations trigger, and how ransomware and KEV signals apply.
## How EMS is scored
The Exploitation Maturity Score (EMS) ranges from 0 to 10, reflecting the real-world exploitation evidence associated with a vulnerability, such as publicly available POCs and exploits, including their popularity and verification status. Stronger indicators such as weaponized exploits, known exploitation status, or confirmed use in ransomware campaigns have a higher influence on the score. A score of 0 means no exploitation activity has been confirmed by supported data sources. Higher scores indicate increasingly strong signals that attackers have enough information to weaponize and deploy the exploit, or that there is evidence of active exploitation in the wild.
Even a single POC with strong popularity indicators, or multiple POCs and exploits combined, can reach a critical score of 8 before confirmation appears in any KEV list or exploit database. This reflects the increased public interest in the vulnerability, which is a powerful exploit maturity indicator, especially in the early days after disclosure.
Scores from 0 to 8 scale linearly with exploitation evidence. EMS 8 corresponds to the critical exploitation threshold: a vulnerability confirmed to have enough evidence of exploitation maturity, which can be reached in various ways. Above 8, the score starts to use logarithmic normalization to increase the granularity for critical scored vulnerabilities, so only vulnerabilities with an exceptional combination of exploitation signals reach 9 or 10. This keeps EMS 10 rare and meaningful, reserved for the highest-priority threats.
When two vulnerabilities have the same EMS, EPSS is used as a tiebreaker.
## What is EMS Escalation
Our Exploitation Maturity Scoring (EMS) system tracks several key indicators of increased risk. When a vulnerability is associated with any of the following, it triggers an EMS Escalation:
1. **Ransomware**:
This escalation indicates that the vulnerability is known to be actively exploited by ransomware groups.
2. **CISA KEV** (Known Exploited Vulnerabilities Catalog):
This escalation signifies that the vulnerability has been added to the Cybersecurity and Infrastructure Security Agency's (CISA) KEV catalog. The KEV catalog lists vulnerabilities that CISA has evidence of being actively exploited in the wild.
3. **POCs** (Proof of Concepts):
This escalation is triggered when a proof-of-concept exploit for the vulnerability becomes publicly available. A POC demonstrates that the vulnerability can be exploited, even if it's not yet used in widespread attacks.
4. **Public Exploits**:
This escalation indicates that functional exploit code for the vulnerability has been released publicly. This is a step beyond a POC, often meaning the exploit is more refined or easier to use.
5. **Weaponized Exploits**:
This is the highest level of EMS Escalation, indicating that the vulnerability is not only being actively exploited but is also part of known attack tools or malware campaigns. This means the exploit has been integrated into a "weapon" used by attackers.
You can read more about Exploitation Maturity Scoring (EMS) [in Binarly Blog](https://www.binarly.io/blog/the-hidden-danger-of-probabilistic-scoring-introducing-exploitation-maturity-score-ems).
## Where to view EMS Escalations
1. **Chronological Event Tracking**: To see a detailed, time-ordered list of EMS Escalation events for a specific image, navigate to the Image Overview page. Within this page, you will find an Escalations tab that provides a chronological history of all exploitation maturity changes.
![]()
2. **Threat Intelligence Monitoring Widget**: This widget can be found on the global dashboard and Image Overview and shows top 10 (by EMS Score) most pressing vulnerabilities present within the platform.
![]()
## Notifications for EMS Escalations
To ensure you are promptly informed of EMS escalations, you can subscribe to receive the [Notifications](/user-guides/advanced/notifications).
# Finding Classes Reference
Source: https://docs.binarly.io/resource-center/finding-classes
Complete reference documentation for all finding classes generated by the Binarly analysis pipeline.
## Overview
Finding classes are the detailed categorization of findings discovered during binary analysis. Each class has a unique identifier, description, and associated notes that indicate its behavior and purpose.
For an overview of how classes are grouped into types for filtering, see [Finding Types & Classes](/resource-center/finding-types).
## Property Notes
The following notes indicate special behaviors for finding classes:
| Note | Description |
| --------------- | ------------------------------------------------------------------------ |
| `artefact` | Property represents or references an artefact discovered during analysis |
| `auto-advisory` | Property can generate an advisory via the Binarly copilot service |
| `deprecated` | Property is no longer generated by current analysis tools |
| `experimental` | Property is in development; schema may change prior to release |
| `informative` | Property is a finding without meaningful severity |
| `internal` | Property is internal to analysis tools/platform |
| `namespace` | Namespace of a group of properties emitted based on rules |
| `aggregate` | Provides an aggregate summary of related findings |
***
## Vulnerability Classes
### Known Vulnerabilities
| Class | Description |
| --------------------------------------- | ----------------------------------------------------------------------------------------- |
| `vulnerability/known-vulnerability` | Known vulnerability previously documented and catalogued |
| `vulnerability/uefi/pkfail` | Untrusted or non-production Platform Key (PK) enabling Secure Boot reconfiguration |
| `vulnerability/uefi/secure-boot-bypass` | Signature databases permit execution of known applications with code execution primitives |
### UEFI Zero-Day Vulnerabilities
| Class | Description |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `vulnerability/uefi/dxe/arbitrary-write-via-pointer-via-nvram-variable` | DXE/SMM memory corruption via NVRAM variable pointer |
| `vulnerability/uefi/pei/arbitrary-write-via-pointer-via-nvram-variable` | PEI memory corruption via NVRAM variable pointer |
| `vulnerability/uefi/smram-write-via-pointer-via-nvram-variable` | SMRAM corruption via unchecked NVRAM variable pointer |
| `vulnerability/uefi/smram-write-via-commbuffer` | SMRAM corruption via unchecked CommBuffer pointer |
| `vulnerability/uefi/smram-write-via-global-buffer` | SMRAM corruption via global buffer outside SMRAM |
| `vulnerability/uefi/smram-write-via-protocol` | SMRAM corruption via protocol interface outside SMRAM |
| `vulnerability/uefi/smram-write-via-save-state` | SMRAM corruption via save state pointer |
| `vulnerability/uefi/dxe/code-execution-via-pointer-via-nvram-variable` | DXE code execution via NVRAM variable function pointer |
| `vulnerability/uefi/pei/code-execution-via-pointer-via-nvram-variable` | PEI code execution via NVRAM variable function pointer |
| `vulnerability/uefi/smm-callout-via-pointer-via-nvram-variable` | SMM callout via NVRAM variable function pointer |
| `vulnerability/uefi/smm-callout-via-boot-services` | SMM callout via UEFI Boot Services |
| `vulnerability/uefi/smm-callout-via-commbuffer` | SMM callout via unchecked CommBuffer pointer |
| `vulnerability/uefi/smm-callout-via-global-buffer` | SMM callout via global buffer outside SMRAM |
| `vulnerability/uefi/smm-callout-via-protocol` | SMM callout via protocol interface outside SMRAM |
| `vulnerability/uefi/smm-callout-via-runtime-services` | SMM callout via UEFI Runtime Services |
| `vulnerability/uefi/smm-callout-via-save-state` | SMM callout via save state pointer |
| `vulnerability/uefi/double-get-variable` | Buffer overflow via shared DataSize between GetVariable calls |
| `vulnerability/uefi/pei-double-get-variable` | Buffer overflow via shared DataSize in PEI phase |
| `vulnerability/uefi/smm-double-get-variable` | Buffer overflow via shared DataSize in SMM |
| `vulnerability/uefi/get-set-variable` | Information disclosure via shared DataSize between Get/SetVariable |
| `vulnerability/uefi/smm-get-set-variable` | SMRAM information disclosure via shared DataSize |
| `vulnerability/uefi/unverified-boot-guard` | Intel Boot Guard verification could not be confirmed |
| `vulnerability/uefi/leaked-boot-guard-km-key` | Leaked Intel Boot Guard Key Manifest private key |
| `vulnerability/uefi/leaked-boot-guard-bpm-key` | Leaked Intel Boot Guard Boot Policy Manifest private key |
***
## Cryptographic Classes
These classes map to the **Cryptographic Material** finding type and appear in the [Cryptographic Materials tab](/user-guides/image-scans/cryptographic-materials). They cover detected algorithms, protocols, certificate issues, and cryptographic key material across all analyzed binary components. For compliance status (weak, deprecated, quantum-vulnerable) for each algorithm, see the [Algorithm Compliance Reference](/resource-center/algorithm-compliance).
### Encryption Algorithms
| Class | Algorithm |
| ---------------------------------------- | ---------------- |
| `crypto/algorithm/encryption/aes` | AES |
| `crypto/algorithm/encryption/3des` | Triple DES |
| `crypto/algorithm/encryption/des` | DES |
| `crypto/algorithm/encryption/blowfish` | Blowfish |
| `crypto/algorithm/encryption/twofish` | Twofish |
| `crypto/algorithm/encryption/camellia` | Camellia |
| `crypto/algorithm/encryption/cast5` | CAST5 |
| `crypto/algorithm/encryption/curve25519` | Curve25519 |
| `crypto/algorithm/encryption/idea` | IDEA |
| `crypto/algorithm/encryption/rc2` | RC2 |
| `crypto/algorithm/encryption/rc4` | RC4 |
| `crypto/algorithm/encryption/rc5` | RC5 |
| `crypto/algorithm/encryption/rc6` | RC6 |
| `crypto/algorithm/encryption/rsa` | RSA (encryption) |
| `crypto/algorithm/encryption/salsa20` | Salsa20 |
| `crypto/algorithm/encryption/hc-128` | HC-128 |
| `crypto/algorithm/encryption/sosemanuk` | Sosemanuk |
| `crypto/algorithm/encryption/skipjack` | Skipjack |
| `crypto/algorithm/encryption/tea` | TEA |
| `crypto/algorithm/encryption/xtea` | XTEA |
| `crypto/algorithm/encryption/xxtea` | XXTEA |
| `crypto/algorithm/encryption/vest` | VEST |
### Hashing Algorithms
| Class | Algorithm |
| ------------------------------------- | ----------- |
| `crypto/algorithm/hashing/md2` | MD2 |
| `crypto/algorithm/hashing/md4` | MD4 |
| `crypto/algorithm/hashing/md5` | MD5 |
| `crypto/algorithm/hashing/sha1` | SHA-1 |
| `crypto/algorithm/hashing/sha224` | SHA-224 |
| `crypto/algorithm/hashing/sha256` | SHA-256 |
| `crypto/algorithm/hashing/sha384` | SHA-384 |
| `crypto/algorithm/hashing/sha512` | SHA-512 |
| `crypto/algorithm/hashing/sha512-224` | SHA-512/224 |
| `crypto/algorithm/hashing/sha512-256` | SHA-512/256 |
| `crypto/algorithm/hashing/sha3-224` | SHA3-224 |
| `crypto/algorithm/hashing/sha3-256` | SHA3-256 |
| `crypto/algorithm/hashing/sha3-384` | SHA3-384 |
| `crypto/algorithm/hashing/sha3-512` | SHA3-512 |
| `crypto/algorithm/hashing/shake128` | SHAKE128 |
| `crypto/algorithm/hashing/shake256` | SHAKE256 |
| `crypto/algorithm/hashing/blake2b` | BLAKE2b |
| `crypto/algorithm/hashing/blake2s` | BLAKE2s |
| `crypto/algorithm/hashing/ripemd160` | RIPEMD-160 |
| `crypto/algorithm/hashing/sm3` | SM3 |
| `crypto/algorithm/hashing/tiger` | Tiger |
| `crypto/algorithm/hashing/djb2` | DJB2 |
| `crypto/algorithm/hashing/fnv` | FNV |
| `crypto/algorithm/hashing/murmur3` | MurmurHash3 |
### RSA Signing Algorithms
| Class | Algorithm |
| ----------------------------------------------------- | --------------------------- |
| `crypto/algorithm/signing/rsa` | RSA |
| `crypto/algorithm/signing/rsa-md2` | RSA-MD2 |
| `crypto/algorithm/signing/rsa-md5` | RSA-MD5 |
| `crypto/algorithm/signing/rsa-ripemd160` | RSA-RIPEMD160 |
| `crypto/algorithm/signing/rsa-sha1` | RSA-SHA1 |
| `crypto/algorithm/signing/rsa-sha224` | RSA-SHA224 |
| `crypto/algorithm/signing/rsa-sha256` | RSA-SHA256 |
| `crypto/algorithm/signing/rsa-sha384` | RSA-SHA384 |
| `crypto/algorithm/signing/rsa-sha512` | RSA-SHA512 |
| `crypto/algorithm/signing/rsa-sha512-224` | RSA-SHA512/224 |
| `crypto/algorithm/signing/rsa-sha512-256` | RSA-SHA512/256 |
| `crypto/algorithm/signing/rsa-sm3` | RSA-SM3 |
| `crypto/algorithm/signing/rsassa-pkcs1-v1-5-sha3-224` | RSASSA-PKCS1-v1\_5-SHA3-224 |
| `crypto/algorithm/signing/rsassa-pkcs1-v1-5-sha3-256` | RSASSA-PKCS1-v1\_5-SHA3-256 |
| `crypto/algorithm/signing/rsassa-pkcs1-v1-5-sha3-384` | RSASSA-PKCS1-v1\_5-SHA3-384 |
| `crypto/algorithm/signing/rsassa-pkcs1-v1-5-sha3-512` | RSASSA-PKCS1-v1\_5-SHA3-512 |
### DSA Signing Algorithms
| Class | Algorithm |
| --------------------------------------- | ------------ |
| `crypto/algorithm/signing/dsa` | DSA |
| `crypto/algorithm/signing/dsa-sha1` | DSA-SHA1 |
| `crypto/algorithm/signing/dsa-sha224` | DSA-SHA224 |
| `crypto/algorithm/signing/dsa-sha256` | DSA-SHA256 |
| `crypto/algorithm/signing/dsa-sha384` | DSA-SHA384 |
| `crypto/algorithm/signing/dsa-sha512` | DSA-SHA512 |
| `crypto/algorithm/signing/dsa-sha3-224` | DSA-SHA3-224 |
| `crypto/algorithm/signing/dsa-sha3-256` | DSA-SHA3-256 |
| `crypto/algorithm/signing/dsa-sha3-384` | DSA-SHA3-384 |
| `crypto/algorithm/signing/dsa-sha3-512` | DSA-SHA3-512 |
### ECDSA Signing Algorithms
| Class | Algorithm |
| ----------------------------------------- | -------------- |
| `crypto/algorithm/signing/ecdsa-sha1` | ECDSA-SHA1 |
| `crypto/algorithm/signing/ecdsa-sha224` | ECDSA-SHA224 |
| `crypto/algorithm/signing/ecdsa-sha256` | ECDSA-SHA256 |
| `crypto/algorithm/signing/ecdsa-sha384` | ECDSA-SHA384 |
| `crypto/algorithm/signing/ecdsa-sha512` | ECDSA-SHA512 |
| `crypto/algorithm/signing/ecdsa-sha3-224` | ECDSA-SHA3-224 |
| `crypto/algorithm/signing/ecdsa-sha3-256` | ECDSA-SHA3-256 |
| `crypto/algorithm/signing/ecdsa-sha3-384` | ECDSA-SHA3-384 |
| `crypto/algorithm/signing/ecdsa-sha3-512` | ECDSA-SHA3-512 |
### EdDSA and Other Signing Algorithms
| Class | Algorithm |
| ---------------------------------- | --------- |
| `crypto/algorithm/signing/ed25519` | Ed25519 |
| `crypto/algorithm/signing/ed448` | Ed448 |
| `crypto/algorithm/signing/sm2` | SM2 |
### Post-Quantum Signing Algorithms
| Class | Algorithm |
| --------------------------------------------- | ------------------ |
| `crypto/algorithm/signing/ml-dsa-44` | ML-DSA-44 |
| `crypto/algorithm/signing/ml-dsa-65` | ML-DSA-65 |
| `crypto/algorithm/signing/ml-dsa-87` | ML-DSA-87 |
| `crypto/algorithm/signing/slh-dsa-sha2-128s` | SLH-DSA-SHA2-128s |
| `crypto/algorithm/signing/slh-dsa-sha2-128f` | SLH-DSA-SHA2-128f |
| `crypto/algorithm/signing/slh-dsa-sha2-192s` | SLH-DSA-SHA2-192s |
| `crypto/algorithm/signing/slh-dsa-sha2-192f` | SLH-DSA-SHA2-192f |
| `crypto/algorithm/signing/slh-dsa-sha2-256s` | SLH-DSA-SHA2-256s |
| `crypto/algorithm/signing/slh-dsa-sha2-256f` | SLH-DSA-SHA2-256f |
| `crypto/algorithm/signing/slh-dsa-shake-128s` | SLH-DSA-SHAKE-128s |
| `crypto/algorithm/signing/slh-dsa-shake-128f` | SLH-DSA-SHAKE-128f |
| `crypto/algorithm/signing/slh-dsa-shake-192s` | SLH-DSA-SHAKE-192s |
| `crypto/algorithm/signing/slh-dsa-shake-192f` | SLH-DSA-SHAKE-192f |
| `crypto/algorithm/signing/slh-dsa-shake-256s` | SLH-DSA-SHAKE-256s |
| `crypto/algorithm/signing/slh-dsa-shake-256f` | SLH-DSA-SHAKE-256f |
| `crypto/algorithm/signing/lms` | LMS |
### MAC Algorithms
| Class | Algorithm |
| -------------------------------------- | --------------- |
| `crypto/algorithm/mac/hmac-md5` | HMAC-MD5 |
| `crypto/algorithm/mac/hmac-sha1` | HMAC-SHA1 |
| `crypto/algorithm/mac/hmac-sha224` | HMAC-SHA224 |
| `crypto/algorithm/mac/hmac-sha256` | HMAC-SHA256 |
| `crypto/algorithm/mac/hmac-sha384` | HMAC-SHA384 |
| `crypto/algorithm/mac/hmac-sha512` | HMAC-SHA512 |
| `crypto/algorithm/mac/hmac-sha512-224` | HMAC-SHA512/224 |
| `crypto/algorithm/mac/hmac-sha512-256` | HMAC-SHA512/256 |
| `crypto/algorithm/mac/hmac-sha3-224` | HMAC-SHA3-224 |
| `crypto/algorithm/mac/hmac-sha3-256` | HMAC-SHA3-256 |
| `crypto/algorithm/mac/hmac-sha3-384` | HMAC-SHA3-384 |
| `crypto/algorithm/mac/hmac-sha3-512` | HMAC-SHA3-512 |
| `crypto/algorithm/mac/hmac-sm3` | HMAC-SM3 |
| `crypto/algorithm/mac/poly1305` | Poly1305 |
### PRNG Algorithms
| Class | Algorithm |
| -------------------------------- | ---------------- |
| `crypto/algorithm/prng/mersenne` | Mersenne Twister |
### Protocols
| Class | Description |
| -------------------------- | --------------------- |
| `crypto/protocol/ssl/v2-0` | SSL v2.0 (insecure) |
| `crypto/protocol/ssl/v3-0` | SSL v3.0 (insecure) |
| `crypto/protocol/tls/v1-0` | TLS v1.0 (deprecated) |
| `crypto/protocol/tls/v1-1` | TLS v1.1 (deprecated) |
| `crypto/protocol/tls/v1-2` | TLS v1.2 |
| `crypto/protocol/tls/v1-3` | TLS v1.3 |
### Certificate Issues
| Class | Description |
| -------------------------------- | ----------------------------------------------- |
| `crypto/certificate/expired` | Certificate has expired |
| `crypto/certificate/invalid` | Certificate has invalid parameters or structure |
| `crypto/certificate/self-signed` | Self-signed certificate found |
| `crypto/certificate/untrusted` | Certificate not signed by recognised CA |
| `crypto/rsa/weak-key-parameters` | Weak RSA key parameters detected |
***
## Mitigation Classes
### General Mitigations
| Class | Description |
| ------------------------------------------- | --------------------------------- |
| `mitigation/known-mitigation-failure` | Known security mitigation failure |
| `mitigation/missing-control-flow-integrity` | Missing CFI (BTI/IBT) protections |
| `mitigation/missing-stack-canaries` | Missing stack canary protection |
### UEFI Mitigations
| Class | Description |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `mitigation/uefi/memory-protection-misconfiguration` | Memory protection policy misconfiguration |
| `mitigation/uefi/missing-rsb-stuffing` | Incomplete Return Stack Buffer stuffing |
| `mitigation/uefi/outdated-dbx` | Outdated forbidden signature database |
| `mitigation/uefi/outdated-amd-microcode-version` | Outdated AMD microcode |
| `mitigation/uefi/outdated-intel-microcode-version` | Outdated Intel microcode |
| `mitigation/uefi/vulnerable-amd-microcode-version` | Vulnerable AMD microcode |
| `mitigation/uefi/vulnerable-intel-microcode-version` | Vulnerable Intel microcode |
| `mitigation/uefi/pei/stack-guard-misconfiguration` | PEI StackGuard misconfiguration |
| `mitigation/uefi/dxe/stack-guard-misconfiguration` | DXE StackGuard misconfiguration |
| `mitigation/uefi/uefiplat-weak-configuration` | Weak UEFI platform configuration |
| `mitigation/uefi/untrusted-ami-test-key` | Non-production AMI test key |
| `mitigation/uefi/untrusted-insyde-test-key` | Non-production Insyde test key |
| `mitigation/uefi/untrusted-phoenix-test-key` | Non-production Phoenix test key |
| `mitigation/uefi/leaked-ami-test-key` | Leaked AMI test key (PKfail) |
| `mitigation/uefi/insyde-fdm-misconfiguration` | Insyde Flash Device Map (FDM) misconfiguration enabling integrity-check bypass |
| `mitigation/uefi/flash-descriptor-misconfiguration` | Intel Flash Descriptor misconfiguration allowing modification of write-protected regions |
| `mitigation/uefi/secure-boot-setup-mode` | Firmware shipped in Setup Mode, allowing enrolment of an arbitrary Platform Key |
### POSIX Mitigations
| Class | Description |
| ------------------------------------------ | ---------------------------------------- |
| `mitigation/posix/fortify-source-disabled` | Fortify Source protection disabled |
| `mitigation/posix/nx-disabled` | No eXecute (NX/DEP) disabled |
| `mitigation/posix/relro-disabled` | RELRO disabled |
| `mitigation/posix/relro-partially-enabled` | RELRO only partially enabled |
| `mitigation/posix/pie-disabled` | Position Independent Executable disabled |
***
## Weakness Classes
| Class | Description |
| ----------------------------------------- | --------------------------------------------- |
| `weakness/posix/not-stripped` | Binary contains symbol information |
| `weakness/posix/rpath-set` | RPATH may allow arbitrary code execution |
| `weakness/posix/runpath-set` | RUNPATH may allow arbitrary code execution |
| `weakness/posix/unsafe-functions/summary` | Aggregate of unsafe function calls |
| `weakness/linux/kernel-configuration` | Linux kernel hardening configuration findings |
***
## Secret Classes
| Class | Description |
| -------------------------- | ------------------------------------------------------------ |
| `secret/credentials` | Potential credentials for accessing restricted resources |
| `secret/api-credentials` | Potential API credentials for unauthorised API calls |
| `secret/oauth-credentials` | Potential OAuth credentials for application impersonation |
| `secret/encryption-key` | Potential encryption key for decrypting protected data |
| `secret/jwt-token` | Potential JWT token for accessing restricted resources |
| `secret/webhook-url` | Potential Webhook URL for compromising workflows |
| `secret/signed-url` | Potential signed URL granting access to restricted resources |
| `secret/private-key` | Potential private key (experimental) |
| `secret/generic` | Potentially sensitive data |
***
## Malware & Suspicious Classes
### Malware
| Class | Description |
| ----------------------------------- | ------------------------------------------------ |
| `malware/known-threat` | Known malware threat |
| `malware/malicious-behaviour` | Detection of potentially malicious behaviour |
| `malware/uefi/implant-hook-install` | UEFI hook installations consistent with bootkits |
### Suspicious (UEFI)
| Class | Description |
| ------------------------------------- | ------------------------------------ |
| `suspicious/uefi/resolve-imports` | PE parsing for resolving imports |
| `suspicious/uefi/resolve-relocations` | PE parsing for resolving relocations |
### Suspicious (POSIX)
| Class | Description |
| ------------------------------------- | --------------------------------------------- |
| `suspicious/posix/executable-data` | DATA segments with execute permissions |
| `suspicious/posix/no-stdlib` | Binary doesn't use standard library |
| `suspicious/posix/packed-elf` | Encrypted or compressed ELF binary |
| `suspicious/posix/reverse-text` | Reverse Text Segment infection technique |
| `suspicious/posix/ctors-dtors` | Suspicious constructor/destructor entries |
| `suspicious/posix/dt-needed` | Modified DT\_DEBUG with suspicious DT\_NEEDED |
| `suspicious/posix/entrypoint` | Suspicious entry point location |
| `suspicious/posix/ifuncs` | Suspicious IFUNC resolvers |
| `suspicious/posix/init-fini` | Suspicious DT\_INIT/DT\_FINI entries |
| `suspicious/posix/plt-got` | Suspicious PLT stub entries |
| `suspicious/posix/pt-note-conversion` | PT\_NOTE conversion infection |
| `suspicious/posix/relocations` | Suspicious relocation table entries |
| `suspicious/posix/text-padding` | Suspicious TEXT segment padding |
***
## Supply Chain Classes
| Class | Description |
| --------------------------------------- | --------------------------------- |
| `supply-chain/known-supply-chain-issue` | Known supply chain security issue |
***
## Patch Classes
| Class | Description |
| --------------------------- | -------------------------------------------------------------------------- |
| `patch/known-vulnerability` | Informative; a patch for a known vulnerability is present in the component |
***
## Artefact Classes
| Class | Description |
| -------------------------------------- | --------------------------------------------- |
| `artefact/uefi/boot-policy-manifest` | Intel Boot Guard Boot Policy Manifest |
| `artefact/uefi/key-manifest` | Intel Boot Guard Key Manifest |
| `artefact/crypto-certificate-material` | X.509 certificates found in component |
| `artefact/crypto-key-material` | Cryptographic keys found in component |
| `artefact/embedded-executable` | Embedded executable files |
| `artefact/related-component` | Related components discovered during analysis |
***
## Metadata Classes
Metadata classes provide informational context about the analysed component:
* `metadata/relation/*` - Component relationships (contains, duplicate-of, dynamic linkage exports/imports/unresolved)
* `metadata/analysis/*` - Analysis metadata (e.g. [code size limits](/resource-center/code-size-limit))
* `metadata/entropy/*` - Entropy analysis data
* `metadata/symbols/*` - Symbol table information (DWARF, ELF, PDB)
* `metadata/hardening/*` - Security hardening summaries (POSIX)
* `metadata/signature/elf/*` - ELF file signature information (HICK, PKCS7, Red Hat, Solaris)
* `metadata/signatures/uefi/secure-boot/*` - UEFI Secure Boot db/dbx entries
* `metadata/uefi/*` - UEFI firmware metadata (Insyde FDM store, GUID-defined sections)
* `metadata/environment/*` - Runtime environment information
***
## Related
* [Finding Types & Classes](/resource-center/finding-types) - How classes are grouped into types for filtering
* [Supported Platforms](/user-guides/about/supported-platforms#analysis-capability-matrix) - Which finding classes are produced for each analyzed target
* [Findings Scope](/user-guides/image-scans/findings-scope) - Configure which finding types are visible per product
* [Cryptographic Detection](/resource-center/cryptographic-detection) - How cryptographic materials are detected
* [Algorithm Compliance Reference](/resource-center/algorithm-compliance) - Compliance status for all algorithm classes
* [Cryptographic Materials Tab](/user-guides/image-scans/cryptographic-materials) - Reviewing crypto findings in the UI
# Finding Types & Classes
Source: https://docs.binarly.io/resource-center/finding-types
Reference documentation for finding types and their associated finding classes.
## Overview
Finding types group related [finding classes](/resource-center/finding-classes) to simplify filtering and scoping. Each finding type maps to one or more finding class patterns.
## Finding Types Reference
| Finding Type | Finding Classes | Description |
| ------------------------ | --------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Cryptographic Material | [`crypto/*`](/resource-center/finding-classes#cryptographic-classes) | Cryptographic assets: algorithms, certificates, keys |
| Secret | [`secret/*`](/resource-center/finding-classes#secret-classes) | Embedded credentials: API keys, tokens, passwords |
| Mitigation Failure | [`mitigation/*`](/resource-center/finding-classes#mitigation-classes) | Missing security mitigations: stack canaries, CFI, ASLR |
| Weakness | [`weakness/*`](/resource-center/finding-classes#weakness-classes) | Code quality issues: unstripped binaries, RPATH issues |
| Unknown Vulnerability | [`vulnerability/uefi/*`](/resource-center/finding-classes#uefi-zero-day-vulnerabilities) | Zero-day vulnerabilities discovered through deep analysis |
| Known Vulnerability | [`vulnerability/known-vulnerability`](/resource-center/finding-classes#known-vulnerabilities) | Publicly documented vulnerabilities with CVEs |
| Supply-Chain Failure | [`supply-chain/*`](/resource-center/finding-classes#supply-chain-classes) | Supply chain integrity issues |
| Dependency Vulnerability | `vulnerability/known-vulnerability` (derived from dependency analysis) | Vulnerabilities in external dependencies |
| Suspicious Code | [`suspicious/*`](/resource-center/finding-classes#suspicious-posix) | Potential tampering or obfuscation patterns |
| Malicious Code | [`malware/*`](/resource-center/finding-classes#malware) | Confirmed malicious behavior |
## Related
* [Finding Classes Reference](/resource-center/finding-classes) - Complete list of all finding classes
* [Findings Scope](/user-guides/image-scans/findings-scope) - Configure which finding types are visible per product
# Hardening Analysis
Source: https://docs.binarly.io/resource-center/hardening-analysis
How the Binarly Transparency Platform detects missing security mitigations and binary weaknesses in compiled binaries.
The Binarly Transparency Platform checks compiled binaries for missing security mitigations and code quality weaknesses through static binary analysis. Findings surface as two finding types: **Mitigation Failure** and **Weakness**.
## Finding types
| Finding Type | Description | Finding Classes |
| ---------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| **Mitigation Failure** | A security hardening control is missing or misconfigured | [`mitigation/*`](/resource-center/finding-classes#mitigation-classes) |
| **Weakness** | A condition that reduces the difficulty of exploitation or expands attack surface | [`weakness/*`](/resource-center/finding-classes#weakness-classes) |
Mitigation failures are gaps in compile-time or runtime protections: a control that should be present and effective is absent or misconfigured. Weaknesses are conditions that make exploitation easier but don't represent a missing control directly.
## Linux userspace hardening
The following checks run against ELF binaries on Linux and POSIX platforms. For UEFI firmware, see [UEFI firmware hardening](#uefi-firmware-hardening).
| Check | What is reported | Analysis method |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------- |
| [**NX / DEP**](https://en.wikipedia.org/wiki/Executable_space_protection) | Whether the NX bit is set | ELF flags |
| [**PIE**](https://en.wikipedia.org/wiki/Position-independent_code) | Whether the binary is position-independent | ELF flags |
| [**RELRO**](https://man7.org/linux/man-pages/man8/ld.so.8.html) | Whether the Relocation Read-Only protection is enabled (Full, Partial, or None) | ELF segment analysis |
| [**Stack canaries**](#stack-canaries) | Per-function coverage percentage | Symbols and cross-references analysis |
| [**FORTIFY\_SOURCE**](https://www.gnu.org/software/libc/manual/html_node/Source-Fortification.html) | Whether FORTIFY\_SOURCE is present at binary level | ELF symbols |
| [**CFI**](#cfi) | Per-function coverage percentage | Instruction and intrinsic scanning |
| [**RPATH**](https://man7.org/linux/man-pages/man8/ld.so.8.html) | Whether RPATH is set, and all path entries | ELF dynamic section |
| [**RUNPATH**](https://man7.org/linux/man-pages/man8/ld.so.8.html) | Whether RUNPATH is set, and all path entries | ELF dynamic section |
| [**Stripped**](https://man7.org/linux/man-pages/man1/strip.1.html) | Whether symbol information is retained | ELF symbol table |
| [**Unsafe functions**](#unsafe-functions) | Which functions, call count, and safe alternatives | Symbol analysis |
### Stack canaries
Most tools report canary protection as a binary-level flag: canary handler symbols are either present or absent. BTP traces the call graph from each non-extern function and reports the percentage that contain an actual call to a canary handler. A binary where handler symbols exist but coverage is incomplete still has unprotected surface. The per-function breakdown is available in the finding detail.
### Unsafe functions
BTP identifies calls to unsafe functions (`strcpy`, `sprintf`, `gets`, and similar) using binary symbols and recovered function information. Each finding reports which functions are called, how many times, and what the safe alternatives are. Findings are classified under CWE-477 (Use of Obsolete Function) and CWE-676 (Use of Potentially Dangerous Function).
### CFI
BTP assesses Control Flow Integrity at the per-function level by scanning for specific instructions and intrinsics rather than relying on compiler-emitted symbols or ELF notes. This identifies CFI gaps in binaries where symbol-based signals are absent or stripped.
### Comparison with checksec
For several checks, BTP goes beyond binary-level flags: canary coverage is reported per-function via symbol analysis, CFI gaps are identified by scanning for specific instructions and intrinsics, and unsafe function calls are detected via symbol and recovered function analysis. These produce signals that flag-based tools cannot report. The table below shows where the two differ; CET SHSTK, PAC, and SafeStack are covered by checksec but not by BTP.
| Check | checksec | BTP |
| ----------------------------- | ---------------------------------------------- | ----------------------------------- |
| NX | ✓ | ✓ |
| PIE | ✓ | ✓ |
| RELRO (Full / Partial / None) | ✓ | ✓ |
| Stack canaries | Binary-level (present/absent) | Per-function with coverage % |
| FORTIFY\_SOURCE | Distinguishes fortified vs fortifiable count | Binary-level only |
| RPATH | Present + all entries (colon-separated) | Present + all path entries |
| RUNPATH | Present + all entries (colon-separated) | Present + all path entries |
| Stripped | ✓ | ✓ |
| CFI | Symbol-based (single + multi-module Clang CFI) | Instruction-byte-based per-function |
| Unsafe functions | — | Call counts + safe alternatives |
| CET — IBT (x86/x86\_64) | ✓ via `.note.gnu.property` | ✓ |
| CET — SHSTK (x86/x86\_64) | ✓ via `.note.gnu.property` | — |
| BTI (ARM64) | ✓ via `.note.gnu.property` | ✓ |
| PAC (ARM64) | ✓ via `.note.gnu.property` | — |
| SafeStack | ✓ via `__safestack_init` symbol | — |
## Linux kernel hardening
Linux kernels built with embedded config support store their configuration inside the binary. BTP extracts and parses this embedded config, then evaluates each `CONFIG_*` option against rules based on [KSPP (Kernel Self-Protection Project)](https://kspp.github.io/Recommended_Settings) recommendations and Binarly custom rules.
Checks are architecture-aware (x86, x86\_64, ARM, ARM64) and kernel-version-aware: rules are only applied to the kernel versions they are relevant for. Each triggered rule generates a finding that reports the CONFIG option name, its current value, and the expected value.
Kernel hardening analysis requires the kernel binary to be built with `CONFIG_IKCONFIG=y`. If the embedded config is absent, no kernel hardening findings are generated for that binary.
## UEFI firmware hardening
UEFI firmware executes before the OS loads and operates at a privilege level above the OS kernel. Misconfigurations at this layer can undermine Secure Boot, memory protection, and CPU vulnerability mitigations — regardless of what the OS has in place.
| Check | What is reported |
| ---------------------------------------------------------------- | ----------------------------------------------------- |
| **Memory protection policy** | Policy misconfiguration type and details |
| **PEI StackGuard** | Misconfiguration present or absent |
| **DXE StackGuard** | Misconfiguration present or absent |
| [**RSB (Return Stack Buffer) stuffing**](#rsb-stuffing) | Absent or incomplete |
| **Intel microcode — outdated** | Detected version |
| **Intel microcode — vulnerable** | Detected version and list of known vulnerabilities |
| **AMD microcode — outdated** | Detected version |
| **AMD microcode — vulnerable** | Detected version and list of known vulnerabilities |
| **Secure Boot dbx (forbidden signatures)** | Outdated revision detected |
| **Secure Boot bypass via known signed applications** | Identified application names |
| **Secure Boot Setup Mode** | Whether Setup Mode is enabled |
| [**AMI non-production test key**](#non-production-test-keys) | Test key identified |
| [**Insyde non-production test key**](#non-production-test-keys) | Test key identified |
| [**Phoenix non-production test key**](#non-production-test-keys) | Test key identified |
| [**PKfail — leaked AMI platform key**](#pkfail) | Leaked key identified |
| **Boot Guard Key Manifest verification** | Verification failure details |
| **Leaked Boot Guard key** | Identified key (Key Manifest or Boot Policy Manifest) |
| **Insyde FDM firmware integrity bypass** | Vulnerable Flash Device Map configuration details |
| **Intel Flash Descriptor** | Writable (unprotected) flash region details |
| **UEFI platform configuration** | Weak configuration details |
### RSB stuffing
RSB stuffing is a Spectre mitigation for x86 firmware. Before transitioning between privilege levels, the firmware should overwrite the Return Stack Buffer with valid entries to prevent speculative execution from leaking data across SMM boundaries. Absent or incomplete stuffing leaves the firmware exposed to RSB underflow attacks.
### Non-production test keys
IBV test keys (AMI, Insyde, Phoenix) are used during firmware development and should never ship in production images. When a production device boots or uses firmware components signed with a test key, the corresponding private key might be publicly available, which means an attacker can use this key to bypass Secure Boot or other mitigations.
### PKfail
PKfail is a Secure Boot Platform Key failure where the private key used to root the Secure Boot chain was leaked or reused across vendors and device models. Binarly's research identified affected firmware across hundreds of device models spanning 12 years of production hardware. A device with a compromised Platform Key has no meaningful Secure Boot guarantee.
## Related
* [Supported Platforms](/user-guides/about/supported-platforms) — Full platform and architecture coverage table
* [Secure by Design findings](/user-guides/image-scans/all-about-details#secure-by-design) — Reviewing mitigation and weakness findings in the platform UI
* [Finding Classes Reference](/resource-center/finding-classes) — Full list of mitigation and weakness classes
* [Finding Types & Classes](/resource-center/finding-types) — How finding types group classes for filtering
* [Component and Version Identification](/resource-center/component-identification) — How components and their versions are identified before any vulnerability matching runs
* [Vulnerability Detection](/resource-center/vulnerability-detection) — Version-based, rule-based, and code-similarity detection of exploitable weaknesses
* [Malicious Code Detection](/resource-center/malicious-code-detection) — Signature and semantic detection of malware, implants, and supply-chain compromises
* [Accuracy & Confidence in Findings](/resource-center/accuracy-confidence)
# ISA/IEC 62443 Compliance Capability Mapping
Source: https://docs.binarly.io/resource-center/isa-iec-62443-compliance-mapping
How the Binarly Transparency Platform maps to ISA/IEC 62443 industrial cybersecurity requirements for firmware and software component security.
ISA/IEC 62443 is the international standard series for cybersecurity in Industrial Automation and Control Systems (IACS). This document maps Binarly Transparency Platform (BTP) capabilities to the standard parts relevant to **product manufacturers**, **system integrators/service providers**, and **asset owners** operating in OT/ICS environments.
This mapping covers BTP's direct analytical and reporting capabilities. ISA/IEC 62443 compliance requires organizational, operational, and network-level controls that extend beyond binary analysis tooling. Where BTP provides supporting evidence rather than full coverage, this is explicitly noted.
***
## Applicable Standard Parts
BTP maps to four standard parts across three distinct ISA/IEC 62443 stakeholder roles:
| Persona | Standard Parts |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| **Manufacturers / Product Suppliers** | 62443-4-1 (SDL), 62443-4-2 (Component Requirements) |
| **System Integrators / Service Providers** | 62443-2-4 (Service Provider Program), 62443-3-3 (System Requirements) |
| **Asset Owners** | 62443-2-1 (Asset Owner Program), 62443-2-3 (Patch Management), 62443-3-3 (System Requirements) |
| Standard Part | Title | BTP Relevance |
| ----------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **IEC 62443-4-1** | Secure Product Development Lifecycle Requirements | Primary — BTP supports all 8 SDL practices as a binary verification layer |
| **IEC 62443-4-2** | Technical Security Requirements for IACS Components | Primary — BTP verifies component-level security posture |
| **IEC 62443-2-3** | Patch Management in the IACS Environment (TR) | Primary — SBOM + VEX enable patch applicability assessment |
| **IEC 62443-2-4** | Security Program Requirements for IACS Service Providers | Primary — BTP enables independent third-party binary verification |
| **IEC 62443-3-3** | System Security Requirements and Security Levels | Primary — BTP provides SL-3/SL-4 assurance evidence for system-level SRs |
| **IEC 62443-2-1** | Security Program Requirements for IACS Asset Owners | Supporting — BTP evidence supports risk-based procurement and continuous compliance |
Parts 62443-1-x (general terminology), 62443-3-2 (risk assessment methodology), and 62443-3-1 (security technologies TR) address foundational and organizational requirements that are outside BTP's analytical scope.
***
## Coverage Summary
Coverage levels: **Full** — BTP directly addresses the requirement. **Partial** — BTP addresses specific aspects; additional controls required. **Evidence** — BTP produces artifacts that support compliance evidence; implementation is outside BTP's scope. **Not Covered** — Outside BTP's analytical scope.
| Requirement Area | Standard Reference | BTP Coverage |
| ------------------------------------------------------------------------------ | ------------------------------------------ | ------------ |
| Third-party component inventory (SBOM) | 62443-4-1 Practice 2 | Full |
| Binary integrity verification | 62443-4-1 Practice 4 / 62443-4-2 CR 3.4 | Full |
| Unsafe function / prohibited API detection | 62443-4-1 Practice 4 | Full |
| Binary hardening verification (ASLR, stack canaries, NX, PIE, RELRO, CFI) | 62443-4-1 Practice 3 / 62443-4-2 CR 3.x | Full |
| Security verification & vulnerability testing | 62443-4-1 Practice 5 | Full |
| CVE tracking and vulnerability disclosure | 62443-4-1 Practice 6 | Full |
| Patch status communication (VEX) | 62443-4-1 Practice 7 / 62443-2-3 | Full |
| Cryptographic material inventory (CBOM) | 62443-4-2 FR 4 (DC) / 62443-4-1 Practice 2 | Full |
| Weak / non-compliant cryptography detection | 62443-4-2 CR 4.1–4.3 | Full |
| Post-quantum cryptography readiness | 62443-4-2 FR 4 (future) | Full |
| Supply chain integrity and tampering detection | 62443-4-1 Practice 2 / FR 3 (SI) | Partial |
| Vulnerability exploitability assessment (Reachability) | 62443-4-2 FR 3 (SI) / 62443-2-3 | Full |
| CISA KEV-tracked vulnerability prioritization | 62443-2-3 | Full |
| Cross-image patch regression tracking | 62443-4-1 Practice 7 / 62443-2-3 | Full |
| Malicious code detection | 62443-4-2 FR 3 (SI) | Full |
| Suspicious code and obfuscation detection | 62443-4-2 FR 3 (SI) | Full |
| UEFI / firmware-specific vulnerability classes | 62443-4-2 EDR requirements | Full |
| Hardcoded credential and secret detection | 62443-4-2 FR 1 (IAC) | Partial |
| Access control enforcement | 62443-4-2 FR 2 (UC) | Evidence |
| Network segmentation and data flow control | 62443-4-2 FR 5 (RDF) | Not Covered |
| Vulnerability intelligence for incident response (VEX, CISA KEV, reachability) | 62443-4-2 FR 6 (TRE) | Partial |
| Patching downtime reduction via reachability prioritization | 62443-4-2 FR 7 (RA) | Partial |
| Third-party binary malware verification (SP.03.02) | 62443-2-4 | Full |
| Third-party CVE monitoring incl. undisclosed dependencies (SP.09.01) | 62443-2-4 | Full |
| SL-3/SL-4 malicious code protection (SR 3.2) | 62443-3-3 | Full |
| Binary configuration and hardening verification (SR 7.6) | 62443-3-3 | Partial |
| Risk-based procurement via binary SBOM delta | 62443-2-1 | Evidence |
| Continuous compliance verification before OT deployment | 62443-2-1 | Evidence |
***
## IEC 62443-4-1: Secure Product Development Lifecycle
IEC 62443-4-1 defines 8 SDL practices that product suppliers must implement. BTP supports all 8 practices as a binary verification layer in the development pipeline.
**Requirement:** Security governance, policy, organizational roles, and SDL support infrastructure.
**BTP Support (Evidence):**
* BTP enforces RBAC with granular roles across organization, product, and image scopes, supporting separation of duties requirements.
* SSO (SAML/OIDC) and mandatory MFA enforce identity governance requirements.
* SOC 2 Type 2 certification (available at trust.binarly.io) provides independent third-party attestation of BTP's security controls.
* On-premises deployment option (Binarly v3) supports air-gapped or isolated environments required for sensitive ICS product development.
* API-driven CI/CD integration supports systematic SDL enforcement rather than ad-hoc scanning.
**Gaps:** Organizational policy authoring, governance documentation, and role assignment workflows are outside BTP's scope.
**Requirement:** Threat modeling, product security requirements, third-party and open-source component security requirements including component inventory.
**BTP Support (Full):**
BTP directly addresses the component inventory and third-party risk requirements that 62443-4-1 Practice 2 mandates:
* **Binary-derived SBOM** (CycloneDX and SPDX): generated from actual compiled binaries rather than vendor-declared manifests, revealing components regardless of documentation accuracy. This satisfies the component inventory obligation for downstream integrators and asset owners.
* **CBOM** (CycloneDX): cryptographic material inventory of every algorithm, protocol, key, and certificate in the binary, used to assess cryptographic security requirements (FR 4).
* **Transitive dependency tracking**: 8 linkage types (direct, static, dynamic, build, derived, vendored, project, unspecified) provide full traceability of how third-party components are incorporated.
* **Dependency vulnerability mapping**: CVE exposure for all detected components including nested transitive dependencies.
The binary-derived approach matters for 62443 compliance: declared SBOMs from vendors frequently omit components. BTP's ground-truth analysis closes this gap.
| Artifact | Format | Relevant 62443-4-1 Requirement |
| --------------- | --------------- | ----------------------------------------------------------------------------------------- |
| SBOM | CycloneDX, SPDX | Maintain software component inventory; assess third-party component security requirements |
| CBOM | CycloneDX | Identify cryptographic requirements for all dependencies |
| Findings Report | PDF, JSON, CSV | Document security issues from third-party and open-source dependencies |
**Requirement:** Secure architecture, attack surface reduction, least privilege by design, design-level security controls.
**BTP Support (Full for verification; Evidence for design):**
BTP verifies that secure-by-design requirements were actually implemented in the binary:
**Binary hardening verification** — detects missing mitigations that represent design failures:
| Mitigation | Finding Class | Architecture |
| ---------------------- | ---------------------------------------------------- | ------------ |
| Stack canary / SSP | `mitigation/missing-stack-canaries` | POSIX |
| ASLR / PIE | `mitigation/posix/pie-disabled` | POSIX |
| NX / DEP | `mitigation/posix/nx-disabled` | POSIX |
| RELRO | `mitigation/posix/relro-disabled` | POSIX |
| Fortify Source | `mitigation/posix/fortify-source-disabled` | POSIX |
| Control Flow Integrity | `mitigation/missing-control-flow-integrity` | POSIX / UEFI |
| UEFI Memory Protection | `mitigation/uefi/memory-protection-misconfiguration` | UEFI |
| Microcode updates | `mitigation/uefi/outdated-intel-microcode-version` | UEFI |
A component that fails these checks does not meet the secure-by-design baseline for its target Security Level.
**Attack surface indicators:**
* Unstripped binaries exposing symbol information (`weakness/posix/not-stripped`)
* RPATH issues enabling library injection attacks (`weakness/posix/rpath-set`)
* Linux kernel hardening configuration findings (`weakness/linux/kernel-configuration`)
**Requirement:** Secure coding guidelines, prohibited function lists, static analysis (SAST), and code review.
**BTP Support (Full):**
BTP performs binary-level static analysis equivalent to post-compilation SAST — detecting implementation failures that survive code review:
**Prohibited/unsafe function detection:**
* `weakness/posix/unsafe-functions/summary`: detects use of `strcpy`, `sprintf`, `gets`, and other functions prohibited by secure coding standards (CERT C, MISRA)
* Unsafe function usage maps directly to the "prohibited functions list" requirement in 62443-4-1 Practice 4
**Binary analysis capabilities:**
* Compiled binary analysis catches issues that source-level SAST misses (inlined functions, LTO artifacts, compiler-introduced patterns)
* Works without access to source code — critical for third-party component verification
* Supports architectures used in IACS: x86, ARM32/64, Xtensa
**Firmware-specific implementation checks:**
* UEFI SMM handler vulnerabilities: SMRAM corruption, SMM callouts, unsafe pointer dereferences
* Malicious or suspicious code patterns: packed ELF, code obfuscation, ifuncs abuse, PT\_NOTE conversion to PT\_LOAD
BTP integrates into CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins, bash) to enforce these checks at every build.
**Requirement:** Security test plans, penetration testing, fuzz testing, dynamic analysis (DAST), regression testing.
**BTP Support (Full for binary V\&V; Evidence for active testing):**
BTP provides binary-level verification and validation that complements active testing:
**Vulnerability verification:**
* Known vulnerability detection (CVE-mapped) with confidence scoring derived from detection method reliability
* Unknown vulnerability detection via FwHunt/VulHunt rules for zero-day class vulnerabilities in UEFI, BMC, and embedded firmware
**Reachability Analysis — exploitability contextualization:**
BTP's [Reachability Analysis](/resource-center/asap) provides four-tier exploitability classification, directly addressing the 62443-4-1 requirement to assess whether identified vulnerabilities are exploitable in the product context:
| Reachability Tier | Exploitability Assessment | V\&V Relevance |
| ----------------- | ---------------------------------- | ------------------------------------------ |
| Direct | Reachable from main/entry-point | Highest priority for V\&V |
| Exported | Reachable from exported interfaces | High — exploitable from component boundary |
| Referenced | Reachable via code references | Medium — requires component interaction |
| Undetermined | Cannot be statically determined | Requires dynamic testing to resolve |
Undetermined reachability findings show where active penetration testing or fuzz testing is needed to resolve exploitability.
**Regression testing support:**
* Cross-image comparison via the [Compare](/user-guides/image-scans/compare) feature and the [Compare Findings API](/api-reference/finding/compare-findings) tracks security regressions between builds to confirm previously remediated vulnerabilities have not been reintroduced.
**Requirement:** Vulnerability disclosure policy, defect tracking, CVE management.
**BTP Support (Full):**
**VEX generation** is BTP's primary contribution to Practice 6. VEX (Vulnerability Exploitability eXchange) encodes per-CVE exploitability decisions in machine-readable format:
| VEX Status | Meaning | 62443-4-1 Practice 6 Use |
| --------------------- | ----------------------------------------------------- | -------------------------------- |
| `affected` | Vulnerability is exploitable in this component | Triggers remediation workflow |
| `not_affected` | Vulnerability is not exploitable (with justification) | Closes false-positive tracking |
| `fixed` | Patch has been applied | Documents remediation completion |
| `under_investigation` | Exploitability not yet determined | Documents active triage status |
VEX formats supported: **OpenVEX**, **CycloneDX VEX** — both CISA-recognized for vulnerability disclosure.
**CVE management:**
* CVE-identified findings are tracked at component level with CPE identifiers
* CISA Known Exploited Vulnerability (KEV) catalog integration prioritizes findings requiring mandatory remediation per CISA BOD 22-01
* Cross-version tracking enables demonstrating remediation to downstream customers
**Requirement:** Patch development, patch distribution documentation, end-of-life policy, patch verification.
**BTP Support (Full):**
**Patch verification via cross-image comparison:**
* Scan the patched binary and compare against the pre-patch baseline using the Compare Findings feature
* API endpoint: `POST /api/v4/grids/findings:gridList` with filters for both image IDs provides machine-readable delta output for automated patch verification in release pipelines (see [Compare Findings API](/api-reference/finding/compare-findings))
**VEX status lifecycle management:**
* Update VEX status from `under_investigation` → `affected` → `fixed` as patches progress
* VEX artifacts accompany firmware update packages to inform downstream asset owners of what was remediated
**Patch applicability for asset owners (62443-2-3 integration):**
* SBOM enables asset owners to determine whether a patched component is present in their deployed systems
* VEX with `fixed` status and component version range data enables patch prioritization without requiring manual analysis
**End-of-life component detection:**
* Dependency findings identify components with known EOL status where the CVE backlog has ceased to be addressed by upstream maintainers
**Requirement:** Product security documentation for integrators and asset owners, hardening guides.
**BTP Support (Full for artifact generation; Evidence for authoring):**
BTP generates the technical artifacts included in security guideline packages delivered with IACS components:
| Artifact | Content | Security Guideline Use |
| -------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------- |
| **SBOM** (CycloneDX / SPDX) | Complete software component inventory | Enables asset owners to assess CVE exposure in their deployment |
| **CBOM** (CycloneDX) | Cryptographic algorithm, key, certificate inventory | Informs cryptographic configuration guidance and PQC migration planning |
| **VEX** (OpenVEX / CycloneDX) | Vulnerability exploitability status | Documents known vulnerability handling for integrators |
| **PQC Compliance Report** (PDF / JSON) | NIST-aligned post-quantum readiness assessment | Executive summary + algorithm migration timeline for customers |
| **Findings Report** (PDF / JSON / CSV) | Full security posture with severity and confidence | Hardening guidance evidence package for integrators |
The PQC report matters most for IACS components with 10–20+ year operational lifespans that will outlive current cryptographic standards.
***
## IEC 62443-4-2: Component Security Requirements
IEC 62443-4-2 defines Component Requirements (CRs) for embedded devices (EDR), host devices (HDR), network devices (NDR), and software applications (SAR) across the 7 Foundational Requirements (FRs) at Security Levels 1–4.
**Scope:** Unique entity identification, authentication mechanisms, credential management.
**BTP Coverage: Partial**
BTP detects credential and authentication failures embedded in firmware, but does not enforce authentication policy at runtime.
**Directly detected violations:**
| Finding Class | CR Violation | Description |
| -------------------------------- | --------------------------------- | -------------------------------------------------------------- |
| `secret/credentials` | CR 1.5 — Authenticator management | Hardcoded usernames and passwords |
| `secret/api-credentials` | CR 1.5 | Hardcoded API keys and service credentials |
| `secret/private-key` | CR 1.5 | Embedded private keys that compromise PKI-based authentication |
| `secret/oauth-credentials` | CR 1.5 | OAuth and JWT tokens |
| `crypto/certificate/expired` | CR 1.8 — PKI certificates | Expired authentication certificates |
| `crypto/certificate/self-signed` | CR 1.8 | Self-signed certificates |
| `crypto/certificate/untrusted` | CR 1.8 | Certificates not anchored to trusted roots |
| `crypto/rsa/weak-key-parameters` | CR 1.8 | RSA keys below minimum strength requirements |
**Gap:** Authentication enforcement (IAC at SL 2–4: MFA, hardware tokens, certificate lifecycle management) is a runtime/operational control outside BTP's scope.
**Scope:** Least-privilege access control, RBAC enforcement, audit logging of access decisions.
**BTP Coverage: Evidence**
BTP itself implements use control requirements for the platform (RBAC, MFA, SSO), but does not perform automated analysis of access control logic in analyzed binaries.
**BTP platform-level UC compliance:**
* Granular RBAC: Admin, Analyst, and Viewer roles scoped to Organization, Product, and Image levels
* All access decisions are logged; audit trail is available for compliance review
* Mandatory MFA and SSO (SAML/OIDC) enforce authentication before use control is applied
**For analyzed components:** Use control logic in firmware (privilege separation, permission checking) requires manual review of binary logic or source code analysis. BTP's reachability analysis can contextualize whether privilege-controlled paths are accessible to untrusted inputs, but automated UC policy verification is not a current BTP capability.
**Scope:** Protection of hardware, software, and communications against unauthorized modification; secure boot; firmware integrity; malware protection.
**BTP Coverage: Full.**
FR 3 (System Integrity) is the foundational requirement most directly addressed by binary analysis:
**Secure boot and firmware integrity (EDR 3.4):**
* UEFI Secure Boot bypass vulnerabilities: `vulnerability/uefi/secure-boot-bypass`
* PKfail and related supply chain compromise of platform keys: `vulnerability/uefi/pkfail`
* UEFI boot script vulnerabilities enabling pre-boot compromise
* BootGuard policy violations
**Firmware integrity verification gaps:**
* `mitigation/missing-control-flow-integrity`: Control Flow Integrity absent — enables hijacking of execution after integrity bypass
* `mitigation/uefi/memory-protection-misconfiguration`: UEFI memory protection policies not enforced
* `weakness/posix/not-stripped`: Symbols present, reducing reverse engineering barrier for integrity attacks
**Malicious and suspicious code (CR 3.8 — Malware protection):**
* `malware/known-threat`: Binary contains signatures matching known malicious firmware implants
* `malware/uefi/implant-hook-install`: Hooks into UEFI boot services — hallmark of firmware persistence implants
* `malware/malicious-behaviour`: Behavioral patterns indicative of malicious intent
* `suspicious/posix/packed-elf`: Binary packing used to evade integrity scanning
* `suspicious/obfuscated-code`: Code obfuscation inconsistent with legitimate firmware
* `suspicious/posix/reverse-text`: Anti-analysis technique indicating potential tampering
* `suspicious/posix/pt-note-conversion`: PT\_NOTE to PT\_LOAD conversion — common ELF rootkit technique
**Communication integrity:**
* Detection of weak or absent integrity mechanisms in protocol implementations
* POSIX and UEFI-level unsafe operations enabling memory corruption attacks against integrity controls
**Scope:** Protection of sensitive data at rest and in transit; encryption algorithm requirements; key management.
**BTP Coverage: Full.**
The CBOM and cryptographic finding classes cover FR 4 directly:
**Weak or non-compliant algorithms:**
| Finding Class | FR 4 Violation |
| -------------------------------- | ---------------------------------------------------------------- |
| `crypto/algorithm/hashing/*` | Insecure hashing (MD5, SHA-1) for data integrity/confidentiality |
| `crypto/algorithm/encryption/*` | DES, 3DES, RC4, or other deprecated ciphers |
| `crypto/algorithm/mac/*` | Weak HMAC or MAC constructions |
| `crypto/protocol/*` | SSL 2.0, SSL 3.0, TLS 1.0, TLS 1.1 |
| `crypto/rsa/weak-key-parameters` | RSA keys below 2048-bit (CR 4.3 minimum) |
| `crypto/weak-ec-parameters` | EC curves below recommended strength |
**Certificate and key management (CR 4.2, EDR 4.1):**
| Finding Class | FR 4 Violation |
| -------------------------------- | ----------------------------------------------------------- |
| `crypto/certificate/expired` | Expired TLS/signing certificates |
| `crypto/certificate/self-signed` | Self-signed certs bypassing trust chain |
| `crypto/certificate/untrusted` | Certificates from non-trusted anchors |
| `secret/private-key` | Private keys embedded in firmware — catastrophic DC failure |
| `crypto/pkcs7-weak-signature` | Weakly signed code or data bundles |
**Post-quantum readiness (CR 4.x for long-lifecycle components):**
The PQC Compliance Report identifies all cryptographic algorithms vulnerable to quantum attacks (RSA, ECC, Diffie-Hellman, SHA-1/SHA-256 for signatures), providing:
* Executive summary with compliance status vs. NIST PQC standards (FIPS 203/204/205)
* Per-algorithm migration urgency ratings
* Component-level quantum exposure inventory from CBOM
IACS components with 10–20 year operational lifespans will outlive the cryptographic algorithms protecting them today.
**Scope:** Network segmentation, zone/conduit enforcement, firewall controls, unidirectional gateways.
**BTP Coverage: Not Covered.**
FR 5 is a network-architectural control requirement. BTP analyzes firmware and software binaries for security vulnerabilities — it does not perform network traffic analysis, firewall rule validation, or zone/conduit topology verification.
Network security tools (firewalls, unidirectional gateways, network monitoring platforms) address FR 5 compliance.
**Adjacent BTP value:** Detection of hardcoded IP addresses and network credentials (`secret/credentials`) that could undermine intended network segmentation controls.
**Scope:** Security event detection, audit log generation, intrusion detection, incident response.
**BTP Coverage: Partial — enables TRE but does not provide operational monitoring.**
BTP generates the vulnerability intelligence that feeds timely response workflows:
**Direct contribution:**
* VEX documents with `under_investigation` and `affected` status formalize the identification phase of incident response for known vulnerability classes
* CISA KEV integration flags findings requiring mandatory 14-day remediation per CISA BOD 22-01
* Reachability analysis contextualizes urgency: Entrypoint reachability findings require immediate response; undetermined reachability enables risk-based prioritization
**Gap:** Audit log generation, SIEM integration, real-time intrusion detection, and incident response orchestration are operational controls outside BTP's scope. SIEM/SOC platforms address FR 6 for operational environments.
**Scope:** DoS resilience, redundancy, resource usage monitoring, backup and recovery.
**BTP Coverage: Partial.**
In OT environments, patching is operationally disruptive — downtime in production systems has direct physical and financial consequences. Unnecessary patching of vulnerabilities that cannot actually be reached is a significant availability risk. BTP's [Reachability Analysis](/resource-center/asap) reduces this risk:
* **Reduces unnecessary patching downtime**: By classifying vulnerabilities as Direct, Exported, Referenced, or Undetermined reachability, BTP allows operators to defer patching of unreachable code without compromising the system's security posture.
* **DoS-relevant vulnerability isolation**: CVSS Availability Impact filtering ([CVSS Vector Filtering](/user-guides/image-scans/cvss-vector-filtering)) isolates findings that directly threaten availability, such as those causing resource exhaustion or service disruption.
* **Vulnerability classes threatening availability**: Missing mitigations (CFI, stack canaries) enable memory corruption attacks weaponizable for DoS; specific CVE classes are flagged with CVSS Impact scores indicating availability impact.
**Gap:** Operational availability controls — redundant architectures, failover mechanisms, backup/restore procedures, and uptime monitoring — are outside BTP's analytical scope. Infrastructure and HA platforms address those requirements.
***
## IEC 62443-2-4: Service Provider Requirements
IEC 62443-2-4 defines the security program capabilities that **system integrators and service providers** must offer when delivering integration and maintenance activities to IACS asset owners. It requires service providers to independently verify that the components they integrate are free from malicious code and continuously monitored for new vulnerabilities — without necessarily having access to vendor source code.
Service providers can fulfill these obligations with BTP's black-box binary analysis:
| 62443-2-4 Requirement | BTP Capability |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **SP.03.02 — Malware Protection**: Verify that delivered third-party software is free from malicious code and firmware implants | BTP scans any binary image without source code access, detecting firmware backdoors, UEFI implants, supply chain tampering, and suspicious code patterns across all 238 finding classes |
| **SP.09.01 — Vulnerability Monitoring**: Maintain continuous monitoring of third-party components for newly disclosed CVEs, including vulnerabilities not disclosed by the original vendor | Binary-derived SBOM reveals statically linked dependencies that vendor manifests routinely omit; BTP maps CVE exposure across all detected components including hidden transitive dependencies |
| **Patch applicability assessment before deployment** | SBOM + VEX enable service providers to determine whether a vendor-issued patch applies to their specific integrated configuration before scheduling disruptive maintenance windows |
| **Independent verification of vendor security claims** | Binary-derived SBOM delta vs. vendor-declared SBOM surfaces undisclosed components, flagging supply chain risk that vendor self-attestation would not reveal |
The core value for 62443-2-4 is the shift from **"trust the vendor"** to **"verify the binary."** Most compliance tooling for service providers relies on vendor-provided SBOMs and self-attestation. BTP converts the opaque binary into an auditable artifact. This enables independent verification that third-party software meets the asset owner's Target Security Level (SL-T), regardless of vendor claims.
***
## IEC 62443-3-3: System Security Requirements
IEC 62443-3-3 defines 110 system-level Security Requirements (SRs) across the 7 Foundational Requirements at Security Levels 1–4. BTP maps directly to the SRs where binary analysis provides concrete verification evidence, particularly at SL-3 and SL-4 where defense against intentional attacks is required.
| SR | Title | BTP Coverage | BTP Capability |
| ------------------- | ---------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **SR 3.2** | Malicious Code Protection | Full | Semantic malware detection identifies firmware implants, backdoors, and Secure Boot bypasses (e.g., LogoFAIL, PKfail) that signature-based AV misses. Provides the higher assurance level required for SL-3/SL-4, where protection against sophisticated intentional violations is mandated. |
| **SR 7.6** | Network and Security Configuration Settings | Partial | BTP extracts configuration metadata from binaries — insecure protocol configurations (SSL/TLS versions, deprecated ciphers), hardening status (RELRO, PIE, NX), and credential artifacts — to verify that third-party software meets the hardening baseline mandated by the system design. Active network configuration enforcement is outside BTP's scope. |
| **SR 3.4** | Software and Information Integrity | Full | Detects integrity violations in firmware binaries: unsigned code, missing CFI, tampered binaries (obfuscated/packed/reversed code), and supply chain compromise artifacts. |
| **SR 1.1 / SR 1.5** | Human User Identification / Authenticator Management | Partial | Detects hardcoded credentials, embedded private keys, and expired PKI certificates in system components that violate authentication integrity requirements. Runtime IAC enforcement is outside scope. |
**SL-3 and SL-4 relevance:** At SL-3 (protection against sophisticated attacks with OT-specific knowledge) and SL-4 (protection against state-level APT attacks), SR 3.2 requires going beyond signature-based malware detection. BTP's semantic analysis — which identifies behavioral patterns, code structure anomalies, and known implant families — meets the depth required at these security levels. Simple AV scanning does not satisfy SL-3/SL-4 for SR 3.2.
***
## IEC 62443-2-3: Patch Management
IEC 62443-2-3 is a Technical Report defining patch management requirements for IACS asset owners and the obligations of product suppliers to support patching activities.
BTP supports both product suppliers (demonstrating patch delivery) and asset owners (assessing patch applicability and urgency):
### For Product Suppliers
| 62443-2-3 Requirement | BTP Capability |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| Maintain component inventory subject to patching | Binary-derived SBOM provides ground-truth component list with versions |
| Communicate CVE exposure to asset owners | VEX documents communicate `affected` / `fixed` / `not_affected` status per CVE per component version |
| Verify patch efficacy | Cross-image comparison confirms vulnerability resolution between pre-patch and post-patch builds |
| Document patch scope | Findings delta report identifies exactly which vulnerabilities were remediated in each release |
### For Asset Owners
| 62443-2-3 Requirement | BTP Capability |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Assess patch applicability to deployed systems | SBOM enables matching vendor-issued SBOMs against known component inventory |
| Prioritize patches by exploitability | VEX `affected` status + Reachability tier + CVSS vector filtering enables risk-based prioritization |
| Prioritize mandatory patches | CISA KEV integration flags actively exploited vulnerabilities requiring mandatory remediation |
| Document patching decisions | Findings export (PDF / JSON / CSV) provides auditable record of known vulnerabilities and remediation status |
***
## Generating ISA/IEC 62443 Compliance Artifacts
BTP generates all standard-required compliance artifacts via API or UI export.
Upload the firmware image and wait for scan completion. For CI/CD integration, use the [CI/CD Integration](/api-reference/use-cases/cicd/overview) pipeline.
```bash theme={null}
curl -H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${PRODUCT_ID}/images/${IMAGE_ID}/sbomReport:cycloneDX?contentType=json" \
-o sbom-cyclonedx.json
# Also available: sbomReport:spdx
```
```bash theme={null}
curl -H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${PRODUCT_ID}/images/${IMAGE_ID}/cbomReport:cycloneDX" \
-o cbom-cyclonedx.json
```
```bash theme={null}
curl -H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${PRODUCT_ID}/images/${IMAGE_ID}/vexReport:openVEX" \
-o vex-openvex.json
# Also available: vexReport:cycloneDX
```
```bash theme={null}
# JSON for machine consumption
curl -H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${PRODUCT_ID}/images/${IMAGE_ID}/cryptographicMaterialsReport?mode=pqc-compliance&contentType=json" \
-o pqc-compliance.json
# PDF for human review and audit packages
curl -H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${PRODUCT_ID}/images/${IMAGE_ID}/cryptographicMaterialsReport?mode=pqc-compliance&contentType=pdf" \
-o pqc-compliance.pdf
```
```bash theme={null}
# Full findings report for audit package
curl -H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${PRODUCT_ID}/images/${IMAGE_ID}?contentType=pdf&imageFields=findings" \
-o findings-full.pdf
# Machine-readable for automated compliance gates
curl -H "Authorization: Bearer ${TOKEN}" \
"${BINARLY_API_URL}/api/v4/products/${PRODUCT_ID}/images/${IMAGE_ID}?imageFields=findings" \
-o findings.json
```
For a single-command script that downloads all artifacts, see [Compliance Artifacts — Automation Script](/api-reference/use-cases/compliance-artifacts#automation-script).
***
## Known Limitations
The following ISA/IEC 62443 requirements are outside BTP's scope as a binary analysis platform:
Do not use BTP as the sole evidence source for these requirement areas. Complementary controls are required to achieve a complete compliance posture.
| Requirement Area | Standard Reference | Recommended Approach |
| ---------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------ |
| Network segmentation, zone/conduit enforcement | FR 5 (RDF) | Industrial firewalls, unidirectional gateways, network security monitoring platforms |
| Real-time operational event monitoring and SIEM | FR 6 (TRE) | Industrial SIEM, OT-aware IDS (e.g., Claroty, Dragos, Nozomi) |
| Redundancy, failover, and uptime monitoring | FR 7 (RA) — operational | Infrastructure redundancy design, HA platforms, availability monitoring |
| Access control enforcement and RBAC in firmware | FR 1/2 (IAC/UC) | Runtime security testing, source code review, penetration testing |
| Security management policies and governance | 62443-4-1 Practice 1 | GRC platforms, policy management tools |
| Threat modeling and security requirements definition | 62443-4-1 Practice 2 | Threat modeling tools (STRIDE, PASTA), security requirements management |
| Active penetration testing and fuzz testing | 62443-4-1 Practice 5 | Dynamic testing tools, dedicated firmware pentest engagements |
| Organizational patch management workflows | 62443-2-3 (procedural) | Vulnerability management platforms, asset owner patch workflows |
| Service provider governance, contracts, and audit programs | 62443-2-4 (non-technical) | Contract requirements, service provider audit programs, GRC platforms |
| Asset owner security program governance | 62443-2-1 (non-technical) | GRC platforms, CSMS/Security Program management tools |
***
## Related Documentation
Generate binary-derived Software Bills of Materials in CycloneDX and SPDX formats.
Inventory all cryptographic algorithms, keys, and certificates in analyzed binaries.
Communicate vulnerability exploitability status to downstream integrators and asset owners.
Assess post-quantum cryptography readiness for long-lifecycle IACS components.
Understand exploitability context for vulnerability prioritization.
Complete reference of all 238 finding classes and their security significance.
# Malicious Code Detection
Source: https://docs.binarly.io/resource-center/malicious-code-detection
How the Binarly Transparency Platform detects malware, implants, and supply-chain compromises using YARA/FwHunt rule matching and semantic behavioral analysis.
Malicious code detection identifies malware, implants, and supply-chain compromises embedded in a scanned image, distinct from [vulnerability detection](/resource-center/vulnerability-detection). Where vulnerability detection looks for weaknesses that could be exploited, malicious code detection looks for evidence that a component has already been tampered with or replaced.
## What's detected
Malicious code detection produces the `malware/*` and `suspicious/*` finding classes documented in [Finding Classes Reference](/resource-center/finding-classes#malware), covering known malware threats, confirmed malicious behavior, and UEFI bootkit-style hook installations, alongside signals like executable data segments or missing standard library usage that can indicate tampering.
The same engines also produce the `supply-chain/*` finding class: confirmed supply chain compromises such as a backdoored dependency, a tampered upstream release, or a leaked signing key, matched by signature the same way a malware family is.
## Rule-based detection
Detection is signature and pattern-based rather than version-based: rules match byte sequences, strings, or firmware-specific characteristics directly against the binary.
### YARA
[YARA](https://yara.readthedocs.io/) is a pattern-matching language for hunting known malware families, implants, and supply-chain compromises by signature. YARA rules can target any binary: executables, firmware images, libraries, or raw file blobs. A small number of shipped YARA rules also match vulnerabilities rather than malicious code, and those produce vulnerability findings.
### FwHunt
[FwHunt](https://github.com/binarly-io/FwHunt) is Binarly's YAML-based rule format for UEFI firmware threat hunting. Because it understands UEFI module structure natively, a FwHunt rule can scope to a specific module by GUID and match known-bad implant patterns within it. Most of the shipped FwHunt rules target vulnerabilities rather than malicious code, covered in [Vulnerability Detection](/resource-center/vulnerability-detection); implant detection is the smaller share of the set.
### Rule sourcing
Binarly ships a default set of YARA and FwHunt rules. Customers can also write, test, and deploy their own rules of either type through the [Custom Rule Manager](/user-guides/rule-management/overview).
## Semantic and behavioral detection
Beyond signature matching, malicious code detection also uses semantic and behavioral analysis that doesn't depend on a predefined rule:
* **UEFI firmware** modules are analyzed semantically to identify bootkit and implant behavior directly in the code, independent of a specific YARA or FwHunt signature.
* **ELF binaries** are analyzed for suspicious behavioral characteristics, such as anomalous section attributes or the absence of expected standard library usage, that can indicate tampering even without a signature match.
This analysis runs on Binarly's built-in engines and, unlike YARA and FwHunt rules, isn't configurable through the Custom Rule Manager.
## Related
* [Vulnerability Detection](/resource-center/vulnerability-detection) - Version-based, rule-based, and code-similarity detection of exploitable weaknesses
* [Finding Classes Reference](/resource-center/finding-classes#malware) - Full list of malware, suspicious-code, and [supply chain](/resource-center/finding-classes#supply-chain-classes) classes
* [Custom Rule Manager](/user-guides/rule-management/overview) - Write and deploy your own YARA or FwHunt rules
# Provenance
Source: https://docs.binarly.io/resource-center/provenance
How the Binarly Transparency Platform extracts installed-package metadata from scanned images, and how it derives vendor/product/CPE/PURL provenance for identified dependencies.
The Binarly Transparency Platform surfaces two distinct kinds of origin data:
* **Extracted component metadata** - the installed-package record (name, version, vendor, and so on) a scanned binary came from, read directly from the package manager's own records inside the image.
* **Dependency provenance** - the vendor, product, version, and (when derivable) CPE/PURL identifiers for a specific identified dependency, used to query and attribute vulnerabilities.
Both are derived from data the platform builds during analysis, not from an external attestation. The last section of this page explains this in-depth.
## Extracted component metadata
When the Binarly Transparency Platform analyzes an OCI image, including Docker images, or a disk image, it reads the package manager's own installed-package records to attribute each binary component to the package that installed it. This works directly from the RPM, dpkg, or Alpine `apk` database found inside the image, so no vendor-supplied manifest is required. Component-level attribution is one of the inputs to the [transitive dependency](/resource-center/transitive-dependencies) classification.
### Package manager coverage
Support differs by image type. OCI image scans read all three package databases; disk image scans currently read RPM only.
| Package manager | OCI images | Disk images |
| --------------- | ---------- | ----------------- |
| RPM | Supported | Supported |
| DEB (dpkg) | Supported | Not yet supported |
| APK (Alpine) | Supported | Not yet supported |
### Extracted metadata
For each package a component is attributed to, the platform extracts the following from the package manager's own records:
| Field | RPM | DEB (dpkg) | APK (Alpine) |
| ----------------- | ----------------------------- | -------------- | ------------ |
| Package name | `NAME` | `Package` | `P` |
| Version | `VERSION`, `EPOCH`, `RELEASE` | `Version` | `V` |
| Architecture | `ARCH` | `Architecture` | `A` |
| Vendor/maintainer | `VENDOR` | `Maintainer` | `m` |
| Source package | `SOURCERPM` | `Source` | `o` |
This metadata does not itself carry a Package URL or CPE identifier. Those are generated separately, as dependency provenance, described next.
Extracted component metadata feeds the component records in SBOM export and the dependency attribution shown for a scanned image, giving you the actual package origin of a component based on what's installed in the image rather than what a vendor claims is present.
## Dependency provenance
When the platform identifies a specific software dependency inside a component, whether embedded or referenced, it attaches a provenance record carrying the vendor, product, and version of that dependency, along with a CPE and Package URL identifier when one can be derived. This is generated from Binarly's [vulnerability data sources](/resource-center/vdb-sources) and version-identification rules, independent of the package manager metadata described above.
A single identified dependency can carry more than one vendor/product pair, because vulnerability data sources have historically used different vendor names for the same software. For example, `util-linux` maps to multiple vendor/product pairs, including `kernel/util-linux` and `andries_brouwer/util-linux`; the platform queries vulnerabilities against every listed pair so a record filed under an older or alternate vendor name isn't missed. This is why the same dependency can appear with more than one Package URL, such as `pkg:deb/kernel/util-linux@2.31.1` and `pkg:deb/andries_brouwer/util-linux@2.31.1`.
Which identity the platform queries vulnerabilities against depends on whether package metadata confirms the dependency and whether the ecosystem has advisory coverage. That decision, and what happens when either condition fails, is covered in [When package data takes precedence](/resource-center/component-identification#when-package-data-takes-precedence). The attribution itself does not change with the outcome: a dependency carries the same vendor, product, CPE, and Package URL whether the finding came from package data or from an identified version.
Dependency provenance is surfaced in finding details when applicable and in [SBOM export](/user-guides/export/sbom).
## What provenance isn't, and what stands in for it
Extracted component metadata and dependency provenance are package and vulnerability identification, not cryptographic proof. The platform does not generate, ingest, or verify build attestations: no SLSA provenance, no in-toto attestation, no Sigstore/cosign signature, no GPG signature verification. A package's presence and version are established by reading the image's own package manager records, not by validating a signed claim about how it was built.
Instead of a signed attestation, rule-based findings carry evidence: the decompiled code and instruction-level annotations showing exactly where the vulnerable pattern was matched in the compiled binary, described in [Debugging Symbols](/resource-center/debugging-symbols). This proves the vulnerable pattern exists in the binary as analyzed. It doesn't prove anything about how that binary was built or signed, which is a separate concern from provenance as documented here.
# Severity Levels
Source: https://docs.binarly.io/resource-center/risk-scoring
**Severity Levels**
* Critical: High-priority vulnerabilities that pose immediate risk.
* High: Issues requiring prompt attention but less urgent than critical.
* Medium: Problems that should be scheduled for resolution.
* Low: Minor vulnerabilities with minimal impact.
* Unspecified: The severity of the finding is undetermined.
Severity is one of several prioritisation signals. See [reachability analysis (ASAP)](/resource-center/asap) for whether vulnerable code is actually reachable, and the [Exploitation Maturity Score](/resource-center/ems-escalations) for real-world exploitation evidence.
# Secrets Detection
Source: https://docs.binarly.io/resource-center/secrets-detection
How the Binarly Transparency Platform detects hardcoded secrets across firmware, container images, source files, and binary artifacts.
The Binarly Transparency Platform detects hardcoded secrets — credentials, tokens, keys, and other sensitive material — across all content within an analyzed image. Detection is architecture-independent: the engine normalizes everything it can extract from an image and scans it for secrets, regardless of the processor architecture the binary targets.
Supported inputs include Docker container images, POSIX-based firmware (router firmware, BMC firmware), disk images, and archives. Any format the platform can unpack is eligible for secrets detection.
## What is analyzed
The engine classifies extracted content into component types and applies the appropriate scanning strategy to each.
| Component class | What is scanned |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Confidential files** | Over 100 recognized files that may contain credentials, e.g. `.bash_history`, `.zshrc` |
| **Source files** | C, C++, C header files, Go, HTML, JavaScript, Java, JSON, Julia, Lisp, Lua, Markdown, OCaml, Perl, PHP, Python, R, Ruby, Shell, SQL, XML, YAML |
| **Plaintext** | Unstructured text content |
| **Python and Java bytecode** | Compiled bytecode (.pyc, .class files) |
| **Docker configs** | Container configuration files |
| **Docker image shadowed files** | Files deleted during the Docker image build process; not present in the final image layer |
| **Git repositories** | Git repository content (including the commit history) and repository configuration |
| **Database files** | LMDB |
| **Shadow password files** | Unix-like `/etc/shadow`, with password hash cracking support |
| **POSIX binaries** | Raw byte content — not disassembled or code-analyzed |
POSIX binaries (ELF executables and shared libraries) are scanned as raw data. The engine does not disassemble or decompile them for secrets detection — it extracts readable strings and applies pattern matching against binary content. Secrets compiled into a binary or embedded as string literals are detected through this method. Some secret types have limited or no coverage in POSIX binaries: secrets that are encoded, split across memory, or reconstructed at runtime are not detected.
## Detection method
The detection engine uses 200+ regex-based rules that match on the structure and format of known secret types: API key prefixes, JWT header patterns, webhook URL formats, URL credentials, and similar signatures. Entropy is calculated for each candidate match and reported alongside the finding.
Shadow password file entries are parsed and each hashed password is checked against a list of 1,000+ common passwords. Supported hash formats: `md5crypt`, `sha256crypt`, and `sha512crypt`.
## What is detected
| Secret type | Examples |
| -------------------------- | --------------------------------------------------------------------- |
| **Credentials** | Service passwords, URL credentials |
| **API credentials** | API keys and tokens |
| **OAuth credentials** | Client secrets, access tokens |
| **Encryption keys** | Symmetric keys embedded in firmware or application binaries |
| **JWT tokens** | Signed authentication tokens |
| **Webhook URLs** | Slack, Teams, and other service webhook endpoints |
| **Generic sensitive data** | Generic API keys and tokens of an unknown format |
| **Signed URL** | Signed URLs with embedded access credentials, e.g. AWS S3 signed URLs |
## Validation
Each secret finding carries a validity status populated by a dedicated validation service that calls out to external APIs to confirm whether the credential is still active.
| Status | Meaning |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Valid** | The credential was confirmed active against an external service |
| **Invalid** | The credential was checked and found inactive or revoked |
| **Undetermined** | The credential could not be checked: the service was unreachable, the secret type is not covered by a validator, or the check returned an inconclusive result |
| **Unspecified** | The validity status is not specified (for finding types other than Secret). Select this value when filtering by validity to include non-secret findings alongside a specific secret validity status. |
All secrets are reported regardless of validity status. `Undetermined` does not mean a credential is inactive: it means the check could not be completed.
Validation runs automatically on SaaS. On on-prem deployments, it is disabled by default.
## Finding details
Each secrets finding includes:
* **Location** — the file path and component within the analyzed image where the secret was found
* **Secret value** — the extracted string, shown as decoded text
* **Entropy** — the entropy of the identified secret value
* **Validity** — the validation status: `Valid`, `Invalid`, or `Undetermined`
* **CWE classification** — the associated weakness class (hardcoded secrets are classified under CWE-798)
## Related
* [Secret finding classes](/resource-center/finding-classes#secret-classes) — Full list of secret finding classes
* [Finding Types & Classes](/resource-center/finding-types) — How finding types map to finding classes
* [Supported Platforms](/user-guides/about/supported-platforms) — Platform and format coverage
* [Stop the Leak: Scanning Containers for Exposed Secrets](https://www.binarly.io/blog/stop-the-leak-scanning-containers-for-exposed-secrets) — Research findings from scanning 80,000+ Docker images across 54 organizations
# Transitive Dependencies
Source: https://docs.binarly.io/resource-center/transitive-dependencies
The eight dependency linkage types the Binarly Transparency Platform records for components found inside a binary.
Every component the platform identifies inside a binary is recorded with a linkage type describing its relationship to the file it was found in. For how the platform decides which linkage applies, see [How linkage is determined](/resource-center/component-identification#how-linkage-is-determined), and [When package data takes precedence](/resource-center/component-identification#when-package-data-takes-precedence) for how a Project result becomes Vendored.
We have eight types of dependency linkage we define for the detection of transitive dependencies.
| Type | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| Direct | Is the entirety of that project or package. |
| Statically linked | Linked into the component as a static library or object file. |
| Dynamically linked | Linked into the component as a dynamic library. |
| Build | Was part of the build process like a compiler or linker. |
| Derived | Was derived from the component like public key parameters extracted from a private key. |
| Project/Package | Is part of that project or package. |
| Vendored | Is distributed as part of a software package with or without modifications but originates from a different project or package. |
| Unspecified | Its linkage could not be determined fully. |
# Vulnerability Database Overview
Source: https://docs.binarly.io/resource-center/vdb-overview
How the Binarly Vulnerability Database aggregates vulnerability data from many sources into variants on each finding and reconciles severity across them.
The Binarly Vulnerability Database (VDB) aggregates vulnerability data from the sources listed in [Vulnerability Data Sources](/resource-center/vdb-sources) and attaches each source's data to the corresponding finding as a variant. This is what lets a finding carry accurate severity, exploitability context, and patch status without you having to reconcile conflicting advisories yourself.
## Finding variants
A vulnerability can be reported under different identifiers across sources: a CVE, a GHSA advisory, a distribution-specific advisory, and so on. Rather than merging these into one record, the VDB keeps each source's data as a separate variant on the same finding. The variant matching a product's configured ecosystem is applied by default, and every other source's data stays available on the finding as an alternative variant.
See [Finding Variants](/user-guides/image-scans/finding-variants) for how the applied variant is chosen and how to configure source priority per product.
## Severity reconciliation
When sources disagree on severity, the VDB picks a CVSS score using a defined source-priority order rather than an arbitrary one, then fills in any missing CVSS vector fields from lower-priority sources without overriding the chosen score. NVD is the default primary source; see [Vulnerability Data Sources](/resource-center/vdb-sources) for how other sources fit into that priority order, and [Finding Variants](/user-guides/image-scans/finding-variants) for how to override source priority per product.
## Supporting correlation data
Beyond the named sources, the VDB maintains additional data to keep matching accurate:
* **CPE correction** - known-incorrect vendor/product associations in NVD's own CPE data are corrected, so a component isn't matched to the wrong CVE because of an upstream CPE error.
* **PURL and CPE cross-referencing** - Package URLs and CPE identifiers for the same component are cross-referenced against each other, supporting the component identifiers described in [Provenance](/resource-center/provenance).
* **Upstream release monitoring** - current stable versions are tracked for supported projects, which helps flag components that are stale or past end-of-life independent of any specific CVE.
## Related
* [Vulnerability Data Sources](/resource-center/vdb-sources) - Full reference for every source the VDB aggregates
* [Vulnerability Detection](/resource-center/vulnerability-detection) - How version-based detection uses VDB data to identify vulnerabilities
* [Provenance](/resource-center/provenance) - How components are attributed to a package, vendor, and product
* [Finding Variants](/user-guides/image-scans/finding-variants) - Configure source priority per product
* [Risk Scoring](/resource-center/risk-scoring) - How exploitation intelligence influences finding priority
# Vulnerability Data Sources
Source: https://docs.binarly.io/resource-center/vdb-sources
Reference for all vulnerability data sources used by the Binarly platform.
## Overview
Binarly aggregates vulnerability intelligence from multiple sources, eliminating the need for customers to build and maintain their own multi-source pipeline. Sources can be prioritized per product to utilize [Finding Variants](/user-guides/image-scans/finding-variants) capabilities.
**NVD (National Vulnerability Database)** is the primary advisory source. Every other source in this list enriches NVD data by adding language- and package-specific advisories, distribution vendor patches, security research, project-level disclosures, and real-world exploitation intelligence. Together they enable findings to carry accurate severity, exploitability context, and patch status across a wide range of targets.
For the best results, sources are matched against the **ecosystem** configured for each product (e.g. Ubuntu, Red Hat, Debian). This allows the platform to cross-reference distribution-specific patches against the relevant advisory sources, ensuring findings reflect the actual patch state of the scanned environment rather than upstream version numbers alone.
Source IDs (e.g. `nvd`, `ghsa`, `brly`) appear in API responses and report exports, and can be used to configure [Finding Variants](/user-guides/image-scans/finding-variants) per product.
***
## Primary Source
| Source | ID | Description | Link |
| ------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| National Vulnerability Database | `nvd` | The authoritative U.S. government CVE repository maintained by NIST. Provides the canonical CVE identifiers, CVSS scores, and advisory details that all other sources are correlated against. | [nvd.nist.gov](https://nvd.nist.gov/) |
***
## Vulnerability Databases
Broad, cross-ecosystem vulnerability databases that complement NVD with independently curated advisory data.
| Source | ID | Description | Link |
| -------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| GitHub Security Advisories | `ghsa` | Curated advisories for open-source packages across many ecosystems, published directly by maintainers and the GitHub Security Lab. | [github.com/advisories](https://github.com/advisories) |
***
## Enrichment Sources
Sources used to enrich and cross-check the canonical CVE data NVD is built on.
| Source | ID | Description | Link |
| ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| CVE List V5 | `cvelist` | The canonical CVE record repository maintained by the CVE Program in the CVE JSON 5.0 format. Provides authoritative CVE descriptions, references, and CNA-assigned metadata used to enrich and cross-check NVD entries. | [github.com/CVEProject/cvelistV5](https://github.com/CVEProject/cvelistV5) |
***
## Language & Package Sources
Language and package-manager-specific advisories provide vulnerability data that NVD alone does not always capture with sufficient detail or timeliness.
| Source | ID | Description | Link |
| ------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Rust Security Advisory Database | `rustsec` | Community-maintained advisories for Rust crates, covering vulnerabilities in the `crates.io` ecosystem. | [rustsec.org](https://rustsec.org/advisories/) |
| Python Security Advisories | `pysec` | Advisories for Python packages distributed via PyPI. | [pypi.org](https://pypi.org/) |
| Go Vulnerability Database | `go` | The official Go team vulnerability database covering modules published to the Go module proxy. | [pkg.go.dev/vuln](https://pkg.go.dev/vuln/) |
| Haskell Security Advisories | `hsec` | Community-maintained security advisories for Haskell packages on Hackage, maintained by the Haskell Security Response Team. | [github.com/haskell/security-advisories](https://github.com/haskell/security-advisories) |
| Python Software Foundation | `psf` | Security disclosures published by the Python Software Foundation. | [python.org](https://www.python.org/) |
| R Security Advisories | `rsec` | Security advisories for CRAN and Bioconductor packages, maintained by the R Consortium in OSV format. | [github.com/RConsortium/r-advisory-database](https://github.com/RConsortium/r-advisory-database) |
***
## Distribution Sources
Linux distribution vendors often backport security fixes without changing upstream version numbers. These sources allow Binarly to account for patched packages in version-based detection and reduce false positives.
| Source | ID | Description | Link |
| --------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Ubuntu Security Notices | `usn` | Canonical's official security advisories for Ubuntu packages. Used to filter patched vulnerabilities in Ubuntu-based binaries. | [ubuntu.com/security/notices](https://ubuntu.com/security/notices) |
| Alpine Linux Security Advisories | `alpine` | Security advisories for Alpine Linux packages, used to filter patched vulnerabilities in Alpine-based binaries and containers. | [security.alpinelinux.org](https://security.alpinelinux.org/) |
| Alma Linux Security Advisories | `alsa` | Security errata for AlmaLinux, a RHEL-compatible distribution. | [errata.almalinux.org](https://errata.almalinux.org/) |
| Alma Linux Bug Advisories | `alba` | AlmaLinux errata for bug-fix updates, used alongside ALSA to track the patch state of AlmaLinux packages. | [errata.almalinux.org](https://errata.almalinux.org/) |
| Alma Linux Enhancement Advisories | `alea` | AlmaLinux errata for enhancement updates, used alongside ALSA to track the patch state of AlmaLinux packages. | [errata.almalinux.org](https://errata.almalinux.org/) |
| Red Hat Security Advisories | `rhsa` | Official Red Hat security errata covering RHEL and related products. | [access.redhat.com](https://access.redhat.com/security/security-updates/) |
| Red Hat Bug Advisories | `rhba` | Red Hat errata for bug-fix updates, used alongside RHSA to track the patch state of RHEL-based packages. | [access.redhat.com](https://access.redhat.com/security/security-updates/) |
| Red Hat Enhancement Advisories | `rhea` | Red Hat errata for enhancement updates, used alongside RHSA to track the patch state of RHEL-based packages. | [access.redhat.com](https://access.redhat.com/security/security-updates/) |
| Rocky Linux Security Advisories | `rockylinux` | Security errata for Rocky Linux, a RHEL-compatible community distribution, covering RLSA advisories and RXSA advisories for the Extras repository. | [errata.rockylinux.org](https://errata.rockylinux.org/) |
| Debian Security Advisories | `debian` | Official Debian security tracker, covering DSA advisories for stable releases, DLA advisories for LTS releases, and package-level CVE tracking. | [security-tracker.debian.org](https://security-tracker.debian.org/) |
***
## Security Vendor Sources
| Source | ID | Description | Link |
| ------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| Binarly Security Research | `brly` | Original vulnerability research produced by Binarly's REsearch team, including firmware and UEFI disclosures not covered by public databases. | [binarly.io](https://binarly.io/) |
***
## Project Sources
Direct vulnerability disclosures maintained by widely-deployed open-source projects. These may include additional context or severity assessments that differ from NVD.
| Source | ID | Description | Link |
| --------------------------- | --------- | ------------------------------------------------------------ | ---------------------------------------------------------------- |
| OpenSSL Security Advisories | `openssl` | Official vulnerability disclosures from the OpenSSL project. | [openssl.org](https://www.openssl.org/news/vulnerabilities.html) |
| cURL Security Advisories | `curl` | Vulnerability disclosures maintained by the cURL project. | [curl.se](https://curl.se/docs/security.html) |
***
## Exploitation Intelligence Sources
These sources provide signals about whether a vulnerability has been actively exploited in the wild or has known public exploit code. They feed directly into [risk scoring](/resource-center/risk-scoring) and [reachability analysis](/resource-center/asap), allowing Binarly to surface the highest-priority findings first.
| Source | ID | Description | Link |
| ------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| CISA Known Exploited Vulnerabilities | `cisa` | CISA's authoritative catalog of CVEs actively exploited in the wild. Inclusion is a strong prioritization signal. | [cisa.gov/kev](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) |
| FIRST EPSS | `first` | The Exploit Prediction Scoring System (EPSS) provides a probability score (0–1) estimating the likelihood a CVE will be exploited within 30 days. | [first.org/epss](https://www.first.org/epss/) |
| Exploit Database | `exploit-db` | Offensive Security's public archive of exploit code and proof-of-concept write-ups. | [exploit-db.com](https://www.exploit-db.com) |
| Metasploit Framework Modules | `metasploit` | Indicates whether a CVE has a weaponized module in the Metasploit penetration testing framework. | [rapid7.com/metasploit](https://docs.rapid7.com/metasploit/) |
| Nomi Sec PoCs | `nomi-sec-pocs` | Aggregated proof-of-concept exploit repositories on GitHub, curated by Nomi Sec. | [github.com/nomi-sec](https://github.com/nomi-sec/PoC-in-GitHub) |
| Nuclei Templates | `nuclei-templates` | Project Discovery's library of Nuclei scanner templates, indicating a CVE has a working detection or exploitation template. | [github.com/projectdiscovery](https://github.com/projectdiscovery/nuclei-templates) |
***
## Related
* [Finding Variants](/user-guides/image-scans/finding-variants) — Configure alternative data sources per product to override default finding data
* [Component and Version Identification](/resource-center/component-identification) — How components and their versions are identified, and when package data takes precedence
* [Vulnerability Detection](/resource-center/vulnerability-detection) — How Binarly identifies vulnerabilities using version-based and rule-based detection
* [Risk Scoring](/resource-center/risk-scoring) — How exploitation intelligence sources influence finding priority
* [Reachability](/resource-center/asap) — How reachability analysis uses exploitability signals to reduce noise
# Vulnerability Detection
Source: https://docs.binarly.io/resource-center/vulnerability-detection
How the Binarly Transparency Platform detects known and unknown vulnerabilities using version-based detection, rule-based semantic detection, and code-similarity analysis.
The Binarly Transparency Platform detects vulnerabilities through several methods: version-based detection, which matches identified components against known-vulnerable version ranges; rule-based detection, which analyzes the actual code semantics of a binary; and, for UEFI firmware, code-similarity and program analysis techniques that don't depend on a version signal or a rule. These methods catch different things and are used together.
## Version-based detection
The primary approach matches an identified component and version against known-vulnerable version ranges sourced through [Vulnerability Data Sources](/resource-center/vdb-sources). How the component and version are established in the first place is covered in [Component and Version Identification](/resource-center/component-identification), and what gets attributed to the result in [Provenance](/resource-center/provenance). Version matching provides broad coverage across every ecosystem the platform identifies, and it produces false positives when a fix has been backported without a version bump.
### Ecosystem filtering
To reduce false positives from backported fixes, the platform matches against the distribution's own security notices instead of upstream version ranges, for the distributions listed under [Distribution Sources](/resource-center/vdb-sources#distribution-sources). This recognizes a patched package even when its version number hasn't changed. It depends on the image carrying package metadata, which is set out in [How backported patches are resolved](/resource-center/component-identification#how-backported-patches-are-resolved).
## Rule-based detection
Rule-based detection analyzes the actual code implementation rather than relying on version numbers, so it can catch both known and unknown vulnerabilities. It works by matching semantic patterns across a binary's disassembly, intermediate representation, and decompiled code, rather than checking for a specific byte sequence.
[VulHunt](https://vulhunt-docs.binarly.io/) is Binarly's semantic rule engine for this kind of detection, covering POSIX executables and libraries as well as UEFI modules. A VulHunt rule can, for example, identify a vulnerable function-call pattern directly rather than checking whether the binary's reported version predates a fix. FwHunt rules provide the same kind of semantic matching scoped specifically to UEFI firmware, including firmware-specific vulnerability patterns such as unsafe SMM callouts.
### Rule sourcing
Binarly's research team authors and ships VulHunt rules as part of the platform. FwHunt rules can also be written and deployed by customers through the [Custom Rule Manager](/user-guides/rule-management/overview), alongside YARA rules for [malicious code detection](/resource-center/malicious-code-detection).
## Code-similarity and program analysis
For UEFI firmware, where a reliable version signal often isn't available, the platform also detects vulnerabilities through two additional techniques that don't rely on a version number or a predefined rule:
* **Known vulnerabilities** are matched by comparing the module's code against reference builds of the component, which identifies it without a version string. See [Hybrid identification for UEFI components](/resource-center/component-identification#hybrid-identification-for-uefi-components).
* **Unknown vulnerabilities** are surfaced through program analysis, including dataflow analysis, symbolic execution, and partial emulation, to identify potentially vulnerable code paths that match no known pattern.
Both are scoped to UEFI modules and complement the semantic rule-based detection VulHunt and FwHunt provide.
## Patch detection
Both detection methods also produce an informative `patch/known-vulnerability` finding when a fix for a known vulnerability is already present in the component, rather than a vulnerability finding itself. This lets you confirm a patch landed without having to re-derive it from a version number alone.
## Related
* [Vulnerability Data Sources](/resource-center/vdb-sources) - The data sources that feed version-based detection
* [Component and Version Identification](/resource-center/component-identification) - How components and their versions are identified before any matching runs
* [Provenance](/resource-center/provenance) - How components and findings are attributed to a package, vendor, and product
* [Finding Classes Reference](/resource-center/finding-classes#known-vulnerabilities) - Full list of vulnerability and [patch](/resource-center/finding-classes#patch-classes) classes
* [Malicious Code Detection](/resource-center/malicious-code-detection) - Signature and semantic detection of malware, implants, and supply-chain compromises
* [Custom Rule Manager](/user-guides/rule-management/overview) - Write and deploy your own FwHunt or YARA rules
* [VulHunt documentation](https://vulhunt-docs.binarly.io/) - Rule syntax, scopes, and the semantic detection engine in depth
# Binary vs. source scanning
Source: https://docs.binarly.io/user-guides/about/comparison/binary-vs-source
How binary scanning compares to source-code scanning across different SDLC security approaches.
Source-code scanning and binary scanning solve different problems. Understanding where each one applies — and where each one falls short — is the starting point for building a complete picture of what's actually in your software.
## Without security checks
![SDLC pipeline with no security checks: code flows from development through build to release without any vulnerability scanning stage]()
An SDLC without binary security checks ships software without inspecting third-party components, precompiled binaries, or transitive dependencies — the categories most likely to carry inherited vulnerabilities. Supply chain attacks, unpatched CVEs, and compliance failures are the direct result.
## Source code scanning
![SDLC pipeline with source code scanning applied to first-party code, leaving precompiled third-party components unanalyzed]()
Source code scanning validates first-party code for vulnerabilities such as injection flaws, buffer overflows, and insecure configurations. It only works on code accessible to the development team.
Many components — third-party dependencies, vendor-supplied libraries, firmware blobs — arrive as precompiled binaries with no source available. If a vulnerable library has no source, the scanner has nothing to analyze. The vulnerability ships undetected.
## SDLC with binary scanning – closing the gaps
![SDLC pipeline with binary scanning at the post-build stage, covering first-party and third-party compiled components together]()
Binary scanning starts from the compiled artifact — the thing that actually runs. It doesn't depend on source code access or vendor-supplied metadata.
The Binarly Transparency Platform scans compiled binaries, including third-party and transitive dependencies, and analyzes them directly. This approach covers categories of software that source-code scanning structurally cannot reach:
* **Statically linked libraries** compiled into the binary without a corresponding package manifest entry
* **Precompiled third-party components** where source code was never available to the buyer
* **Backported patches** where a vendor fixes a CVE without changing the version number, making version-based matching wrong in both directions
* **Proprietary and closed-source components**, including drivers, firmware blobs, and vendor-supplied modules
Binary scanning integrates at the post-build stage, after all components have been compiled and linked. Security teams scan the final artifact — first-party and third-party code together — without requiring access to the original source. This makes it a practical complement to source-code scanning, covering the portions of the supply chain that source analysis cannot reach.
# The Binarly advantage
Source: https://docs.binarly.io/user-guides/about/comparison/the-binarly-advantage
How Binarly's binary-native analysis finds what source-code tools structurally cannot, and the capabilities that set it apart.
## Why binary analysis is structurally different
Source-code scanning tools — including most SCA platforms — analyze what developers *declared* was in their software. They read package manifests, lock files, and import statements.
Binary analysis starts from the compiled artifact — the thing that actually runs. It doesn't require source code access and doesn't depend on vendor-supplied metadata. Every component present in the binary is identified directly, regardless of whether it appears in any SBOM, package manifest, or documentation.
This distinction matters most for four categories of content that source-code tools structurally cannot reach:
* **Statically linked libraries** compiled directly into an executable without leaving a package manifest entry
* **Precompiled third-party components** where source code was never available to the buyer
* **Transitive dependencies** pulled in by third-party components and compiled into the binary, invisible to tools that only resolve declared direct dependencies
* **Backported patches** where a vendor fixes a CVE without changing the version number, making version-based matching wrong in both directions
## Primary focus
Binarly is purpose-built for firmware, embedded Linux, and compiled application binaries — the artifacts that actually ship or run. This is the only way to assess firmware, third-party components delivered without source code, and software where a vendor-supplied SBOM hasn't been independently verified.
The platform supports UEFI firmware, BMC firmware (OpenBMC, AMI MegaRAC), Embedded Linux, QNX, Android, Docker containers, Java (JARs, WAR/EAR, and JVM bytecode), Python applications, and Linux ELF binaries. Cross-architecture analysis covers x86, ARM, and XTensa.
## Eight differentiating capabilities
### Unknown vulnerability class detection
Most platforms detect known CVEs by matching component versions against a vulnerability database. Binarly also detects entire vulnerability classes by analyzing code behavior semantically. The Binarly Analysis Engine decompiles binaries, constructs call graphs, and performs data-flow analysis to identify patterns matching known CWEs — independent of whether a CVE has been assigned. This means Binarly can find vulnerabilities before a CVE is assigned, not only after.
### Patented reachability analysis
Binarly's [reachability analysis](/resource-center/asap) ([U.S. Patent 12,287,885](https://patents.google.com/patent/US12287885)) traces actual execution paths through a binary to determine whether vulnerable code is reachable by an attacker. The analysis is environment-aware: it accounts for the runtime context, not just whether a call path exists in the abstract. The result is a filtered finding list where every item has a defensible basis for prioritization — not a list of every theoretical vulnerability in every linked library.
### Exploitation Maturity Score
The [Exploitation Maturity Score](/resource-center/ems-escalations) (EMS) ranks findings using real-world evidence: public proof-of-concept code availability, ransomware group usage data, private telemetry, and CISA KEV catalog status. CVSS measures theoretical severity. EMS reflects whether attackers are actively exploiting a vulnerability. Combined with reachability analysis, EMS gives security teams a prioritized list grounded in current threat activity.
### Patented CBOM and PQC compliance
Binarly generates a [Cryptography Bill of Materials](/user-guides/export/cbom) from binary analysis ([U.S. Patent 12,153,686](https://patents.google.com/patent/US12153686)), inventorying every cryptographic algorithm, certificate, key, and protocol present in the binary. Cryptographic reachability analysis identifies which assets are actively used. PQC compliance checks map findings to NIST IR 8547 and CNSA 2.0 requirements across three readiness tiers, with migration timelines assigned to each finding.
### Original vulnerability research
Binarly has published [204 public disclosures](https://www.binarly.io/advisories) across 84 products and 15 vendors. LogoFAIL — a class of vulnerabilities in UEFI image parsers — affects billions of devices. PKfail exposed Secure Boot Platform Key failures across 200+ device models spanning 12 years of production hardware. The research produces the detection rules that run in the platform today. It also validates the methodology: the same analysis engine that found LogoFAIL is the one scanning your binaries.
### UEFI firmware depth
UEFI firmware analysis goes beyond surface-level component inventory. Binarly parses UEFI volumes, modules, and driver execution order; detects image parser vulnerabilities (as demonstrated by LogoFAIL); identifies Secure Boot policy weaknesses; and flags hardening gaps at the firmware level.
### Secrets detection
Binarly identifies hardcoded secrets — credentials, API keys, private keys, and cryptographic material — embedded in compiled binaries and firmware. Unlike pattern-matching tools that scan source files, secrets detection works directly on the binary artifact, finding secrets that were embedded at compile time or introduced through third-party components.
### Malware and tampering detection
Binarly detects malicious implants, backdoors, and binary tampering at the firmware and application level. Analysis identifies code patterns consistent with known malware families and flags anomalies that indicate post-build modification — providing confidence that a firmware image or compiled binary hasn't been compromised between build and deployment.
# Customer support
Source: https://docs.binarly.io/user-guides/about/customer-support
How to get help with the Binarly Transparency Platform.
## Support
The Binarly team offers technical support via an email-based ticketing system. For inquiries or issues, contact [support@binarly.io](mailto:support@binarly.io). Support hours are Monday through Friday, 9 AM to 6 PM EST. Weekend and after-hours support is available for critical issues. Response times may vary depending on issue severity, priority, and availability.
For general inquiries, visit [www.binarly.io](https://www.binarly.io/) or email [info@binarly.io](mailto:info@binarly.io).
For compliance documentation, security certifications, and trust-related inquiries, visit [trust.binarly.io](https://trust.binarly.io/).
# Deployment architectures
Source: https://docs.binarly.io/user-guides/about/deployment-architectures/SaaS-vs-onprem
The Binarly Transparency Platform is available as a fully managed SaaS offering and as a self-hosted on-premises installation for air-gapped and regulated environments.
The Binarly Transparency Platform ships in two deployment models. Most organizations start with SaaS, which requires no infrastructure investment. On-premises deployments are available for customers whose data classification policies, network boundaries, or regulatory requirements prohibit the use of cloud-hosted services.
## SaaS
Binarly hosts and operates the platform on your behalf. Each customer instance is fully isolated — no multi-tenancy, no shared data storage, no cross-customer access of any kind. Anonymous, aggregate performance and health telemetry is collected to maintain cluster availability; beyond that, customers retain complete control over their platform and the data within it.
SaaS is the right choice when your organization can route binary artifacts to an external service. The benefits:
* **No infrastructure to provision.** No Kubernetes cluster, persistent storage, or database to stand up or maintain.
* **Automatic updates.** New detection rules, platform features, and threat intelligence are delivered without action on your part.
* **Instant onboarding.** Accounts are activated by logging in. CI/CD integrations are a single API token away.
* **Live threat intelligence.** The platform has continuous access to Binarly's threat feeds and research-backed detection updates.
## On-premises
On-premises deployments run the same platform inside your own infrastructure. The installation is Kubernetes-based and mirrors SaaS functionality, with narrow exceptions for features that require external connectivity — live threat intelligence feeds and remote-assisted support, for example.
On-premises is appropriate when data must stay within organizational or sovereign boundaries:
* **Classified and government environments** where policy mandates that analysis artifacts never leave controlled networks.
* **Air-gapped networks** with no permissible path to an external service.
* **Regulated industries** where compliance frameworks prohibit cloud processing of sensitive firmware or software artifacts.
* **Internally developed source code** that cannot be transmitted outside the organization under IP or contractual terms.
The table below summarizes which capabilities are available in each deployment model.
| | SaaS | On-premises | On-premises air-gapped |
| ------------------------------- | ---- | ----------- | ---------------------- |
| **Live threat intelligence** | ✓ | Partial | — |
| **Automatic updates** | ✓ | Partial | — |
| **AI-assisted analysis** | ✓ | Partial | — |
| **Remote support** | ✓ | Partial | — |
| **Dev/SecOps integration** | ✓ | ✓ | ✓ |
| **Self-managed infrastructure** | — | ✓ | ✓ |
Partial means the feature is available when the on-premises deployment has outbound internet access. Air-gapped deployments receive threat intelligence and detection rule updates through periodic offline update packages delivered by Binarly.
# Security & compliance
Source: https://docs.binarly.io/user-guides/about/security
How the Binarly Transparency Platform handles deployment security, access control, authentication, and compliance certification.
## Isolated instances
Aside from [on-premises deployment](/user-guides/about/deployment-architectures/SaaS-vs-onprem), Binarly offers isolated instance deployments for customers requiring dedicated infrastructure. Each isolated tenant runs on dedicated compute and storage within its own cloud account or project, with complete data segregation.
Customer images are encrypted and stored in a unique object store bucket. Authentication is managed by a dedicated OIDC server within the isolated instance, and all database instances are unique to each tenant. Each customer receives a dedicated API URL with a randomly generated 8-character subdomain. Optional access for Binarly's Customer Success team requires 2FA and is used only for support purposes.
## Access control
### RBAC
Binarly provides organization management with granular role-based access control (RBAC). Administrators assign permissions to users based on their responsibilities, controlling access to features and data at the role level.
See [Roles](/user-guides/rbac/roles) and [User management](/user-guides/rbac/user-management) for configuration details.
### Authentication
#### 2FA
The Binarly Transparency Platform requires multi-factor authentication (MFA) for all logins.
#### Single Sign-On (SSO)
The platform supports SSO via SAML and OIDC, allowing organizations to integrate existing identity providers.
## Compliance
### SOC 2
Binarly holds [SOC 2 Type 2 certification](https://secureframe.com/hub/soc-2/what-is-soc-2). Compliance documents and reports are available at [trust.binarly.io](https://trust.binarly.io/).
# Supported platforms
Source: https://docs.binarly.io/user-guides/about/supported-platforms
Binary formats, operating systems, processor architectures, and analysis capabilities supported by the Binarly Transparency Platform.
## Black-box unpacking
The platform unpacks uploaded binaries using an engine based on [unblob](https://unblob.org), extended with Binarly-specific handlers for UEFI firmware images and Docker container images. The engine detects container types automatically, unpacks contents recursively, and preserves metadata (timestamps, permissions) where the format allows.
7-Zip, AR, ARC, ARJ, Autel ECC, CAB, CPIO (binary, portable ASCII, portable ASCII CRC, portable old ASCII), D-Link (encrypted image, FPKG, SHRS), DMG, Engenius (partial), HP (BDL, IPKG), Instar (BNEG, HD), LZH, MSI (partial), multi-sevenzip, Netgear (CHK, TRX v1/v2), Partclone, QNAP NAS, RAR (partial), StuffIt (SIT, SIT v5), TAR (Unix, USTAR), Xiaomi (HDR1, HDR2), ZIP (partial)
Partial support: RAR and ZIP cover non-encrypted archives only. MSI uses CFB-based extraction only, so extracted filenames reflect CFB internal names rather than on-disk installer paths. Engenius does not support all firmware versions.
Android EROFS, Android Sparse, CramFS, ExtFS (ext2/ext3/ext4), FAT (FAT12/FAT16/FAT32), ISO 9660, JFFS2 (new and old), NTFS, RomFS, SquashFS (v1, v2, v3, v4, including Broadcom, DD-WRT, and big-endian variants), UBI, UBIFS, YAFFS
bzip2, compress, GZIP (standard and multi-volume), LZ4 (standard, legacy, and skippable frames), Lzip, LZMA, LZO, UZIP, XZ, zlib, ZSTD
QCOW2, Raw disk image, VHD, VHDX, VMDK
ELF (32-bit and 64-bit)
**Binarly extensions:**
* UEFI firmware images (PI firmware volumes, FFS file systems, PE32/PE32+ sections)
* Vendor UEFI/BIOS update packages: Acer, Asus, Dell, Fujitsu, Gigabyte, HP, HPE, Intel, Lenovo, MSI, Samsung, Supermicro, and LVFS
* BMC firmware: AMI MegaRAC SPX, Supermicro, Nuvoton NPCM8XX
* FIT (Flattened Image Tree) images
* NVIDIA SoC firmware capsules (Spark, Grace, Tegra)
* U-Boot bootloader images
* Docker container images (OCI and Docker-format layer tarballs)
## Supported environments
What you can submit for static binary analysis.
* X86
* ARM32/64 (and variants)
* XTensa
* UEFI firmware and update packages
* BMC firmware
* Microcode (Intel and AMD)
* U-Boot bootloader
* Zephyr RTOS firmware
* OP-TEE kernel
* QNX
* OpenWRT
* Android Open Source Project (AOSP)
* Yocto Linux
* Buildroot Linux
* Linux distributions (Rocky, Ubuntu, Red Hat, etc.)
* HPE Aruba OS
* Cisco IOS/NX
* Linux kernel images (uImage and zImage)
* Java (JARs, WAR/EAR archives, JVM bytecode)
* Linux ELF binaries
* Android packages (APK)
* Lua bytecode
* Python packages, source code, and bytecode
* Docker container images
## Detection coverage
What the analysis engine identifies within submitted binaries.
The platform identifies weak, vulnerable, or potentially compromised cryptographic assets (`crypto/*`):
* Weak private and public keys
* x509 expired certificates
* PKCS7 bundles
* Leaked or compromised keys
* Cryptographic protocols
* Cryptographic algorithms
Intel BootGuard manifests and UEFI Secure Boot policy are inventoried as UEFI artefacts (`artefact/uefi/boot-policy-manifest`, `artefact/uefi/key-manifest`) alongside cryptographic material. Boot Guard integrity failures and leaked Boot Guard keys are reported as supply-chain failures.
Embedded secrets in files within analyzed binaries (`secret/*`):
* API credentials
* OAuth credentials
* Encryption keys
* JWT tokens
* Webhook URLs (e.g. Slack webhooks)
* Generic credentials (e.g. URLs with Basic Auth)
Secrets can be validated against external services. Each secret carries a validity status: Valid, Invalid, Undetermined, or Unspecified.
See [Secrets Detection](/resource-center/secrets-detection) for full input scope and component class coverage.
Zero-day vulnerabilities discovered through semantic code analysis (`vulnerability/uefi/*`). The Binarly Analysis Engine decompiles binaries, constructs call graphs, and performs data-flow analysis to identify vulnerability classes independent of any CVE assignment.
UEFI-specific classes include:
* SMM callouts via NVRAM variables, CommBuffer, Boot Services, Runtime Services, protocols, and save state
* SMRAM corruption via pointers, CommBuffer, global buffers, protocols, and save state
* DXE and PEI memory corruption and code execution via NVRAM variable function pointers
* Buffer overflows via shared DataSize between GetVariable calls (double-get pattern)
* SMRAM information disclosure via shared DataSize
* Microcode vulnerabilities in UEFI-based firmware
Publicly documented vulnerabilities with assigned CVEs (`vulnerability/known-vulnerability`). Findings include CVSS, EPSS, and Exploitation Maturity Score (EMS), reachability analysis, and decompiled pseudocode evidence.
Also covers UEFI-specific known vulnerabilities:
* PKfail: untrusted or non-production Platform Key enabling Secure Boot reconfiguration (`vulnerability/uefi/pkfail`)
* Secure Boot bypass: signature databases permitting execution of known applications with code execution primitives (`vulnerability/uefi/secure-boot-bypass`)
CISA Known Exploited Vulnerabilities (KEV) catalog status and ransomware campaign association are shown on individual finding detail pages.
Known vulnerabilities in external dependencies detected through dependency analysis (`vulnerability/known-vulnerability`). Findings are organized by dependency in the Dependencies tab, showing affected components, version ranges, and earliest safe versions where a fix is available.
Known supply chain integrity issues (`supply-chain/known-supply-chain-issue`). These surface deviations from expected supply chain integrity, for example components built from tampered sources or known compromised toolchains.
Also covers Intel Boot Guard integrity issues:
* Boot Guard verification could not be confirmed
* Leaked Boot Guard Key Manifest private key
* Leaked Boot Guard Boot Policy Manifest private key
Missing security mitigations and code quality issues that increase exploitability or indicate insecure development practices.
**Linux / ELF mitigation failures** (`mitigation/*`):
* Missing stack canaries
* Missing Control Flow Integrity (CFI, IBT, BTI)
* NX/DEP disabled
* RELRO disabled or partially enabled
* PIE disabled
* Fortify Source disabled
**Linux / ELF weaknesses** (`weakness/*`):
* Unstripped binaries containing symbol information
* RPATH or RUNPATH set (potential for arbitrary code execution via library hijacking)
* Use of unsafe C/C++ functions
* Linux kernel hardening configuration gaps
**UEFI firmware mitigations** (`mitigation/uefi/*`):
* Memory protection policy misconfiguration
* PEI and DXE StackGuard misconfiguration
* Incomplete RSB stuffing
* Outdated or vulnerable Intel and AMD microcode
* Outdated Secure Boot forbidden signature database (dbx)
* Secure Boot Setup Mode enabled
* Non-production test keys (AMI, Insyde, Phoenix)
* Leaked AMI platform key (PKfail)
* Writable Intel Flash Descriptor regions
* Weak UEFI platform configuration
See [Hardening Analysis](/resource-center/hardening-analysis) for analysis depth and per-platform check details.
Potential tampering or obfuscation patterns (`suspicious/*`). Flags anomalous PE parsing behavior in UEFI modules, including unusual import resolution and relocation handling, that may indicate a modified or implanted binary.
Confirmed malicious behavior (`malware/*`). The platform identifies malicious implants, hooks, embedded executables, and firmware backdoors. Findings include the module name and type, detected capabilities, virtual addresses, and industry references using ATT\&CK and Malware Behavior Catalog (MBC) classifications.
## Analysis capability matrix
This matrix maps each analyzable target to the [finding classes](/resource-center/finding-classes) the platform can produce for it. Rows are the component types that analysis binds to; columns link to the corresponding section of the Finding Classes reference.
Column key:
* **Cryptography** - [Cryptographic Classes](/resource-center/finding-classes#cryptographic-classes)
* **Known (code)** - [Known Vulnerabilities](/resource-center/finding-classes#known-vulnerabilities) found by code and semantic analysis
* **Known (version)** - [Known Vulnerabilities](/resource-center/finding-classes#known-vulnerabilities) found from package, version, and ecosystem data
* **Zero-day** - [UEFI Zero-Day Vulnerabilities](/resource-center/finding-classes#uefi-zero-day-vulnerabilities)
* **Mitigation** - [Mitigation Classes](/resource-center/finding-classes#mitigation-classes)
* **Weakness** - [Weakness Classes](/resource-center/finding-classes#weakness-classes)
* **Secret** - [Secret Classes](/resource-center/finding-classes#secret-classes)
* **Malware** - [Malware Classes](/resource-center/finding-classes#malware)
* **Suspicious** - [Suspicious Classes](/resource-center/finding-classes#suspicious-posix)
* **Supply chain** - [Supply Chain Classes](/resource-center/finding-classes#supply-chain-classes)
| Target | Cryptography | Known (code) | Known (version) | Zero-day | Mitigation | Weakness | Secret | Malware | Suspicious | Supply chain |
| ------------------------------------------- | ------------ | ------------ | --------------- | -------- | ---------- | -------- | ------ | ------- | ---------- | ------------ |
| UEFI firmware | Yes | Yes | | Yes | Yes | Yes | | Yes | Yes | Yes |
| Linux / POSIX ELF | Yes | Yes | Yes | | Yes | Yes | Yes | Yes | Yes | Yes |
| Linux kernel image | | | Yes | | | Yes | | | | |
| U-Boot bootloader | | Yes | Yes | | | | | | | |
| Zephyr / MCUboot | | | Yes | | | | | | | |
| OP-TEE | | Yes | | | | | | Yes | | Yes |
| Java (JAR / bytecode) | Yes | | Yes | | | | Yes | Yes | | Yes |
| Android APK | Yes | | | | | | | | | |
| Python (package / bytecode) | Yes | | | | | | Yes | Yes | | Yes |
| Lua (source / bytecode) | | Yes | | | | | Yes | Yes | | Yes |
| Source code and configs | | | | | | | Yes | Yes | | Yes |
| Docker container config / layers | | | | | | | Yes | Yes | | Yes |
| Git repositories | | | | | | | Yes | Yes | | Yes |
| Cryptographic material (certificates, keys) | Yes | | | | | | | | | |
**Recursive unpacking.** Composite inputs (UEFI firmware and update packages, BMC firmware, disk images, archives,
Docker images, APKs) are unpacked into their constituent components, and each extracted component is analyzed
according to its own row. For example, ELF binaries inside a Docker image or firmware image receive the full Linux /
POSIX coverage, and native libraries inside an APK are analyzed as ELF.
**How known vulnerabilities are detected.** **Known (code)** findings come from code and semantic analysis of the
component itself. **Known (version)** findings come from package, version, and ecosystem matching, and are also
surfaced as dependency vulnerabilities. See [Vulnerability Detection](/resource-center/vulnerability-detection) for
both methods. Malware and supply-chain findings are produced by signature, rule, and semantic analysis engines and
apply broadly to the targets above — see [Malicious Code Detection](/resource-center/malicious-code-detection).
**Managed runtimes.** Cryptographic detection for Java and Python is API-based and does not cover post-quantum
algorithms. See [Cryptographic Detection](/resource-center/cryptographic-detection).
Alongside these findings, the platform also emits informative [artefacts](/resource-center/finding-classes#artefact-classes) (embedded executables, certificates, keys, Boot Guard manifests) and [metadata](/resource-center/finding-classes#metadata-classes) (symbols, hardening summaries, entropy, component relationships) for the relevant targets.
# Use cases
Source: https://docs.binarly.io/user-guides/about/use-cases
Primary use cases for the Binarly Transparency Platform: secure product development, third-party risk management, and post-quantum cryptography readiness.
## Secure product development
![SDLC pipeline showing where binary scanning integrates post-build, covering first-party and third-party components before release]()
Hardware OEMs and software vendors use Binarly to validate compiled binaries before products ship. The scan runs post-build — after all components have been compiled and linked — which is the point where the binary is in its final form and source-code scanning no longer reaches the full picture.
**Problem:** Traditional SCA tools run against source code and package manifests. They miss vulnerabilities in statically linked libraries, precompiled third-party components, and firmware blobs where source is unavailable. By the time a binary reaches production, these blind spots have already been inherited.
**Solution:** The Binarly Transparency Platform scans the compiled binary directly. The Binarly Analysis Engine decompiles, constructs call graphs, and performs data-flow analysis across the full binary — first-party code and all embedded third-party components. Known CVEs are detected by [identifying components in the binary itself](/resource-center/component-identification), rather than by reading a package manifest, a declared SBOM, or a file hash. Unknown vulnerability classes are detected through semantic code behavior analysis. Results include a binary-derived SBOM, prioritized findings, and reachability data. The result: a triage list grounded in what's actually reachable, not what's theoretically possible.
**How it integrates:** Post-build in CI/CD pipelines via GitHub Actions, GitLab CI, Jenkins, or the REST API. Scans typically complete within minutes for most binary sizes. Findings can gate the release or feed directly into JIRA for remediation tracking.
***
## Third-party risk management
![Procurement workflow showing binary scan of vendor-supplied firmware before deployment, with discrepancy comparison against vendor SBOM]()
Enterprise security and procurement teams use Binarly to inspect vendor-supplied firmware and software before it enters their environment. Vendor SBOMs and attestations describe what a vendor says is in their product. Binary analysis shows what's actually there.
**Problem:** Statically linked dependencies, undeclared components, and backported patches are invisible to tools that work from manifests alone. Accepting a vendor SBOM without binary validation means accepting self-attestation as ground truth.
**Solution:** Binarly scans the firmware or software binary provided by the vendor and generates an independent SBOM from the binary itself. The platform compares vendor-supplied SBOMs against binary ground truth, surfaces discrepancies, and flags known and novel vulnerabilities present in the actual binary — not in the declared component list. The result: objective evidence replacing vendor self-attestation.
**How it integrates:** Vendor onboarding workflows, pre-procurement security assessments, and ongoing supplier monitoring. Scan results become a vendor security posture report, a SBOM attestation, or evidence for contractual security requirements.
***
## Post-quantum cryptography readiness
![PQC readiness workflow showing CBOM generation from binary analysis mapped to CNSA 2.0 and NIST IR 8547 compliance tiers]()
Binarly generates a Cryptography Bill of Materials (CBOM) from binary analysis and maps every cryptographic asset to [CNSA 2.0](https://www.nsa.gov/Resources/Commercial-National-Security-Algorithm-Suite-2-0/) and [NIST IR 8547](https://csrc.nist.gov/publications/detail/ir/8547/final) compliance requirements. This applies to any binary where you need to know what cryptographic algorithms are actually in use — not what documentation says should be there.
**Problem:** Quantum-resistant cryptography migration requires knowing what algorithms are deployed across every system and component. Most organizations can't answer that question for third-party firmware and compiled software where source code is unavailable. Standard inventory tools work from metadata; cryptographic assets embedded in binaries are invisible to them.
**Solution:** The Binarly Analysis Engine identifies every cryptographic algorithm, key, certificate, and protocol present in the binary. Cryptographic reachability analysis determines which assets are actively used versus merely present. The [CBOM output](/user-guides/export/cbom) maps each finding to NIST IR 8547 compliance tiers and includes migration timelines: immediate action required for MD5 and DES, RSA phase-out by 2030, full PQC migration by 2035. See [PQC reports](/user-guides/export/pqc) for export format details.
**How it integrates:** CNSA 2.0 compliance assessments for National Security Systems (new acquisitions must be compliant by January 2027). PCI DSS 4.0 cryptographic inventory requirements (Requirements 4.2.1.1 and 12.3.3). Internal PQC migration planning for any organization with compiled firmware or software in scope.
# Why Binarly
Source: https://docs.binarly.io/user-guides/about/why
The Binarly Transparency Platform gives software producers and enterprise buyers ground-truth visibility into compiled software and firmware — without source code access.
## The binary is ground truth
Most software supply chain tools tell you what a vendor *declared* was in their product. Binarly tells you what's actually there.
Statically linked libraries don't appear in package manifests. Vendors backport security fixes without changing version numbers, so hash-based and version-based matching misses patched components entirely. Any tool that works from metadata alone inherits every error and omission in that metadata.
The Binarly Transparency Platform scans compiled binaries — firmware images, executables, containers, and libraries — and derives a ground-truth picture of what software is actually running: every component, every cryptographic asset, every known and novel vulnerability.
## Four problems traditional tools don't solve
**Lack of visibility.** Without source code access, it's difficult to know exactly what's inside a compiled binary or firmware image — especially code from third-party vendors. Binary analysis removes that dependency entirely.
**Unknown threats.** Most scanners only match known CVEs by version number. They miss zero-day vulnerabilities, entire classes of bugs, and malicious implants with no existing signature. The [Binarly Analysis Engine](/user-guides/about/supported-platforms) detects vulnerability classes semantically, independent of CVE assignment.
**Alert fatigue.** Version-based scanners report every CVE in every linked library, including vulnerabilities that can't be reached in the specific binary. [Reachability analysis](/resource-center/asap) and the [Exploitation Maturity Score](/resource-center/ems-escalations) filter findings to what's actually exploitable and actively targeted. The result is a prioritized list of findings teams can act on, not a backlog of theoretical risks.
**Complex supply chains.** A single firmware image can contain code from dozens of suppliers. Statically linked dependencies are embedded directly in the binary and invisible to manifest-based tools. Binarly identifies every component regardless of how it was packaged.
## What Binarly detects
The platform identifies nine categories of findings within compiled binaries and firmware:
* **Known vulnerabilities** — CVE matches with CVSS, EPSS, Exploitation Maturity Score, and reachability data
* **Unknown vulnerability classes** — zero-day patterns detected through semantic code analysis, independent of CVE assignment
* **Dependency vulnerabilities** — known vulnerabilities in embedded third-party components, organized by dependency
* **Cryptographic material** — weak keys, expired certificates, compromised keys, cryptographic protocols and algorithms
* **Secrets** — hardcoded API credentials, OAuth tokens, encryption keys, JWT tokens, and generic credentials
* **Supply-chain failures** — components built from tampered sources, compromised toolchains, and Boot Guard integrity issues
* **Mitigation failures and weaknesses** — missing stack canaries, CFI, NX/DEP, RELRO, PIE, Fortify Source, and use of unsafe functions
* **Suspicious code** — anomalous parsing behavior and obfuscation patterns that may indicate a modified or implanted binary
* **Malicious code** — confirmed malware implants, hooks, embedded executables, and firmware backdoors, classified using ATT\&CK and MBC
See [Supported platforms](/user-guides/about/supported-platforms) for the full coverage table by platform and architecture.
## Who uses it
Hardware OEMs and software vendors integrating Binarly into CI/CD pipelines to validate compiled binaries before shipping. The goal: catch vulnerabilities in your own stack and in every third-party component before a product reaches a customer.
Enterprise security and procurement teams assessing third-party firmware and software before deployment. The goal: verify vendor claims against binary ground truth and reduce exposure to supply chain risk.
Both segments use the same platform in different workflows. Producers run Binarly post-build inside CI/CD. Consumers run it during vendor onboarding and procurement review.
## Research that validates the engine
Binarly's detection engine is built on original vulnerability research. [204 public disclosures](https://www.binarly.io/advisories) across 84 products and 15 vendors include LogoFAIL — a UEFI image parser vulnerability class affecting billions of devices — and PKfail, a Secure Boot Platform Key failure present in 200+ device models across 12 years of production hardware.
This research isn't separate from the platform. It produces the detection rules, validates the analysis methodology, and establishes that the Binarly Analysis Engine finds vulnerabilities that other tools miss.
## Next steps
* [Use cases](/user-guides/about/use-cases) — how software producers and enterprise buyers put this into practice
* [The Binarly advantage](/user-guides/about/comparison/the-binarly-advantage) — the specific capabilities that set Binarly apart from source-code scanning tools
# JIRA Integration
Source: https://docs.binarly.io/user-guides/advanced/jira
An important part of any vulnerability management program is the actionability of the scan or assessment results. Providing developers, security engineers, and product owners with important details for each finding in an accessible and familiar format is paramount to timely mitigation and remediation. Our API-based foundation allows for integration into any tool set or workflow. Because Atlassian JIRA is a popular tool among our install base, we have provided a direct, two-way integration for ease of use and seamless interoperability.
## Configuring JIRA Integration
Prerequisites
* Administrative Permissions: Administrative privileges in Jira are required. If you do not have these permissions, coordinate with a team member who can grant access or assist with the integration.
* Compatibility: These instructions are applicable for Jira version 8.
To ensure a seamless integration between the Binarly Platform and Jira, follow these steps:
Step 1: Specify Your Jira Instance
Identify your Jira instance URL. For example:
[https://CompanyDomain.atlassian.net](https://CompanyDomain.atlassian.net)
Step 2: Authorize the Binarly Platform
1. Access Jira Settings:
* Open Jira and click the settings icon.
* Select Products from the menu.
2. Navigate to Application Links:
* Under the Integrations section, choose Application Links.
3. Create a New Application Link:
* Click Create Link and paste the Binarly Application Link provided by your organization.
4. Review and Configure the Application Link:
* In the Review Link section, provide the Binarly Dashboard details as prompted.
* Ensure the Create Incoming Link option is selected.
5. Enter Authentication Details:
* Input the following:
* Consumer Key: Provided by Binarly.
* Consumer Name: A recognizable name for this integration (e.g., "Binarly Platform").
* Public Key: Provided by Binarly.
6. Finalize the Application Link:
* Click Continue and wait for the Application Link creation process to complete.
7. Verify Integration in the Binarly Platform:
* In the Binarly Dashboard, click Verify to authenticate the connection and confirm the integration.
# Notifications
Source: https://docs.binarly.io/user-guides/advanced/notifications
The core purpose of Notifications feature is to promptly inform the user about important updates and [Escalations](/resource-center/ems-escalations) in vulnerabilities. It helps to follow the vulnerability trends and check them against specific customer data to prioritize urgent trends of new critical or high-impact vulnerability appearance or track the trend when previously known vulnerabilities got exploited by malicious threat actors.
## Subscriptions
Users receive alerts specifically for escalations in vulnerabilities for the Products they're subscribed to. When a vulnerability associated with a product escalates in severity or new critical information becomes available, the users will be notified, enabling them to focus the attention where it's needed most.
### How to subscribe to a Product
1. Locate the product you want to subscribe to:
* You can do it by browsing the list of products on the Products page.
2. Click "Subscribe" button.
![]()
## Types of Notifications
The following channels are available:
1. **Email Notifications**: Receive alerts directly in your inbox. You can choose to receive these alerts on a **daily** or **weekly** basis, providing a summary of relevant vulnerability [Escalations](/resource-center/ems-escalations). Emails will be sent to the **address configured in the user account**.
2. **Slack Notifications**: Slack notifications support per-event (immediate) alerts, meaning you are notified as soon as an escalation occurs for a product you are subscribed to. We utilize [Slack incoming webhook URLs](https://api.slack.com/incoming-webhooks) to deliver these notifications directly to your designated channels.
### Configure Notification Settings
1. Access Notification Settings
* You can do it by navigating to "Settings" page behind the user icon.
2. Click "Save Settings" button.
![]()
# Automatic Advisories
Source: https://docs.binarly.io/user-guides/export/advisories
The Binarly Transparency Platform provides automatic advisory generation for UEFI vulnerabilities that can be shared internally, with third-party vendors, or publicly. These advisories consolidate all available technical information about a UEFI vulnerability.
## Advisory Content
Each automatically generated advisory includes technical details about the UEFI vulnerability: a summary with a concise description of the security issue, affected component details including the vulnerable UEFI module's name, GUID, and hash values, and a risk assessment in the form of the vulnerability's CVSS vector and score. Below is an excerpt of a generated advisory.
![An example BTP Automatic Advisory]()
The technical analysis provides the specific address of the vulnerable function within the module, decompiled function body showing the actual vulnerable code, a technical breakdown of the vulnerable code lines and how they can be exploited, and suggested fixes and mitigation strategies to address the vulnerability.
## Generating Advisories
The Automatic Advisory can be generated from the finding details page (see below).
![The finding details context menu option for Automatic Advisories]()
1. Navigate to the [finding details page](/user-guides/image-scans/all-about-details#finding-details) for a UEFI vulnerability
2. Click the three-dot menu (**...**) in the finding details interface
3. Select **Get Advisory** from the dropdown menu
4. Choose your preferred output format:
* **PDF**: Formatted document suitable for formal distribution and presentation
* **Markdown**: Text-based format ideal for integration with documentation systems or further editing
If there exists a [Jira ticket](/user-guides/advanced/jira) for the finding, the advisory can be stored in the Jira ticket as an attachment instead of being downloaded. To do this, choose "Attach to Jira ticket" in the "Get Advisory" menu and select the desired format: PDF or Markdown (MD).
## Use Cases
Automatic advisories serve multiple communication scenarios. They can aid **internal communication** by sharing detailed vulnerability analysis with internal security teams and supporting incident response and vulnerability management processes. Advisories can also be used for **3rd-party vendor coordination** with firmware developers or OEMs, providing technical details to facilitate patch development, and coordinated disclosure processes without the need of giving 3rd-party access to the Binarly Transparency Platform. Finally, automatic advisories support **public disclosure** by providing standardized vulnerability reports that ensure consistent and comprehensive information sharing with the security community and maintain technical accuracy.
# CBOM (Cryptographic Bill of Materials)
Source: https://docs.binarly.io/user-guides/export/cbom
Export a Cryptographic Bill of Materials (CBOM) to inventory all cryptographic algorithms, certificates, and keys discovered in a scanned image.
A Cryptographic Bill of Materials (CBOM) is a structured inventory of all cryptographic materials discovered within a scanned binary image. BTP generates CBOMs in [CycloneDX](https://cyclonedx.org/) JSON format - an open standard for describing software and cryptographic assets in supply chains.
## What Is Included
A BTP-generated CBOM includes:
* **Cryptographic algorithms** - all detected implementations with class identifier, parameters, and location within the image
* **Protocols** - detected SSL/TLS protocol versions
* **Certificates** - X.509 certificates with issuer, subject, validity period, signature algorithm, and key parameters
* **Keys** - cryptographic key material with key type and size
* **Component references** - binary component within the image where each material was found
## Generating a CBOM
Navigate to the product view and find the image you want to export.
Click the **CBOM** feature tag in the image grid row, or open the action menu and select **Download CBOM**.
From the image detail view, **Download CBOM** is also available in the action menu.
The downloaded file is a CycloneDX JSON document ready for use in compliance tooling, automated pipelines, or manual review.
## Relationship to SBOM
The CBOM complements the SBOM by focusing on cryptographic materials rather than software components:
| | SBOM | CBOM |
| ------------ | --------------------------------- | ------------------------------------------ |
| **Tracks** | Libraries, packages, dependencies | Algorithms, certificates, keys |
| **Format** | CycloneDX or SPDX | CycloneDX |
| **Use case** | Software composition analysis | Cryptographic compliance and PQC readiness |
## Post-Quantum Readiness
The CBOM provides an inventory of quantum-vulnerable algorithms (RSA, ECDSA, DSA, ECDH) for migration planning per NIST IR 8547. For compliance-focused reporting with per-algorithm migration guidance, see the [PQC Compliance Report](/user-guides/export/pqc).
## Programmatic Access
* [CBOM Report API](/api-reference/report/cbom-report) - Endpoint reference
* [Compliance Artifacts](/api-reference/use-cases/compliance-artifacts) - Automation scripts
## Related
* [Cryptographic Materials Tab](/user-guides/image-scans/cryptographic-materials)
* [Algorithm Compliance Reference](/resource-center/algorithm-compliance)
* [PQC Compliance Report](/user-guides/export/pqc)
# PQC Compliance Report
Source: https://docs.binarly.io/user-guides/export/pqc
Advances in quantum computing will eventually result in cryptographically-relevant quantum computers (CRQC) that are able to decrypt, retroactively, data that is protected by quantum-weak cryptographic algorithms. As a response, NIST issued guidance on what algorithms to replace until 2035. The Binarly Transparency Platform scans images for quantum-weak cryptographic algorithms and produces a detailed Post-Quantum Compliance report that lists all instances of quantum-weak algorithms, affected image components, and NIST recommendations for which algorithms should replace them and until what date.
The PQC Compliance Report provides organizations with comprehensive visibility into their cryptographic posture and readiness for the post-quantum era. This specialized report analyzes binaries to identify cryptographic implementations that may be vulnerable to future quantum attacks and provides actionable guidance for migration to quantum-resistant algorithms.
## Report Contents
The PQC Compliance Report delivers a structured analysis of cryptographic compliance across multiple sections:
The report begins with an **executive summary** (see below) that provides high-level takeaways including an overview of the analyzed system, overall compliance level assessment, and a strategic migration plan with prioritized recommendations for addressing quantum-weak cryptographic implementations. Report metadata includes creation timestamps and detailed product information about the analyzed binary, including version, build information, and scope of analysis.
![Excerpt of the PQC compliance report's executive summary.]()
Next is the **current compliance status** which delivers a comprehensive breakdown of all detected cryptographic algorithms with their type and parameters, post-quantum compliance status for each implementation, NIST guidance regarding recommended replacements where applicable, and security assessment for each compliant algorithm (see below). The compliance status section concludes with a recommended migration timeline for short, mid and long-term.
![Excerpt of the PQC compliance report's compliance summary.]()
This is followed by an exhaustive list of **individual algorithm findings** organized by compliance status (see below). The detailed findings section provides comprehensive information about each cryptographic implementation discovered during the analysis, categorized by their quantum resistance status.
![Excerpt of the PQC compliance report's finding list.]()
Each algorithm finding, grouped by compliance status, includes the component name and function addresses for precise identification, detailed algorithm parameters and reachability analysis results, specific NIST guidance with recommended replacement algorithms where applicable.
The report concludes with a detailed description of the **analysis scope and methodology** employed during scanning, an overview of the NIST IR 8547 framework for transition to post-quantum cryptography, limitations and assumptions of the analysis, and references to relevant standards and guidance documents.
## Generating a Report
The Binarly Transparency Platform provides multiple access points for generating PQC Compliance Reports, enabling users to initiate cryptographic analysis from different contexts within the platform.
PQC Compliance reports can be generated through two primary methods: **product dashboard** (below, left side), where users navigate to the product dashboard and access the report generation functionality through the options menu to obtain a comprehensive view of all cryptographic implementations across the entire product scope, and **image dashboard** (below, right side), where users utilize the generate button from the cryptographic materials tab on the image dashboard to create reports specific to individual firmware images, enabling targeted analysis of cryptographic implementations within a specific binary or firmware version.
![Main dashboard interface]()
![Main dashboard interface]()
The platform generates PQC Compliance reports in two distinct formats to accommodate different organizational needs: **PDF format**, which has been described above, aimed at stakeholder presentations and compliance documentation, and **JSON format**, which contains all cryptographic algorithm findings present in the PDF while providing additional technical metadata including component SHA-256 hash values, implementation types, and structured data fields to facilitate automated processing. Beyond downloadable reports, the Binarly Transparency Platform provides immediate visibility into PQC compliance status through the cryptographic materials tab. This interface displays findings and compliance overview data directly within the platform.
## Integration with CBOM
PQC Compliance Reports complement the platform's [Cryptographic Bill of Materials (CBOM)](/user-guides/export/cbom) capabilities by providing compliance-focused analysis of identified cryptographic materials. While CBOM catalogs all cryptographic components, the PQC report specifically evaluates their quantum resistance and provides migration guidance aligned with NIST standards.
## Programmatic Access
Generate PQC reports programmatically using the Binarly API:
* [PQC Report API](/api-reference/report/pqc-report) - Endpoint reference
* [Compliance Artifacts](/api-reference/use-cases/compliance-artifacts) - Automation scripts
# Image and Detail Reports
Source: https://docs.binarly.io/user-guides/export/reports
The Transparency Platform offers multiple reporting and output generation options to assist with understanding findings, facilitating information sharing, and supporting mitigation efforts. The type of output generated varies depending on the selected format and the context from which it is generated.
Different outputs are tailored to meet the needs of various audiences. For instance, a high-level PDF report provides an overview of findings within a specific image, making it suitable for stakeholders who require concise summaries. Conversely, an image-specific JSON output is designed for machine consumption, enabling integration with tools or pipelines to streamline remediation or issue tracking processes.
Additionally, the platform supports specialized outputs for Software Bill of Materials (SBOM) and our patented Cryptographic Bill of Materials (CBOM) generated from Binary. These outputs offer unparalleled visibility into third-party components and cryptographic materials embedded within analyzed binaries. This exposes a view into the true composition of the software regardless of what is attested to in a vendor supplied bill of materials. This ensures a comprehensive understanding of the security posture of components, supporting both compliance and risk management efforts.
From Main image view, summary and detail reports can be generated for all findings associated with a specific image. These reports can be generated into PDF or JSON formats. It should be noted that images such as large Docker containers or BMC Firmware images for
example Can contain a large amount of dependency vulnerabilities that in turn produce large PDF reports.
Options exist to allow the generation of summary PDF and JSON reports from a filtered set of criteria. This further helps to focus the report recipient or consumer on specific findings of interest. For example: a specific component, vulnerability type, or severity of findings could be selected and then subsequently reported on.
Reports generated from this main View are typically used to convey the overall security posture or vulnerability status of an analyzed image as a whole. Deep vulnerability details should beGenerated individually for improved consumability, visibility, and actionability.
### Image Report Examples
Image Summary PDF Report
![]()
Image Detailed PDF Report
![]()
## Finding Detail Reports
Reports generated from within the detail view of a finding are typically used to convey a highly detailed View of the vulnerability including all aspects of the finding. this provides the recipient with all the information necessary toFurther investigate or take actions to remediate or mitigate the finding. This output will include all industry references (CVE , CVSS, CWE, EPSS), descriptions, and component details for the selected finding. For specific finding types Known, Unknown vulnerabilities and Malicious Code) extended component vulnerability location details will also be included in the report. This includes Pseudo code representations of the findings where applicable.
### PDF finding Output Examples
* Unknown vulnerability finding detail report
![]()
![]()
* Dependency Finding Detail Report ![]()
![]()
* Cryptographic Material finding Detail Report ![]()
### JSON finding Output examples
* Known vulnerability finding detail output
![]()
* Dependency finding detail output
![]()
* Cryptographic Material finding detail output ![]()
### Bulk Finding Export
Findings can be exported as CSV files. This bulk export includes all columns from the findings grid, as a direct export of what the findings grid currently displays.
![Screenshot of the findings grid with the CSV export menu item selected.]()
This feature is especially valuable for bulk data analysis, creating specialized reports, or importing findings data into other security management tools and workflows.
# SBOM (Software Bill of Materials)
Source: https://docs.binarly.io/user-guides/export/sbom
The Binarly Transparency Platform provides robust SBOM (Software Bill of Materials) generation capabilities, delivering comprehensive visibility into components and dependencies within Firmware, Embedded Linux, and Container (Docker) binaries . SBOM’s our generated completely from the uploaded and analyzed binary. With no need to ingest or upload a vendor supplied BOM, this provides an inventory of the actual contents of the file or package regardless of what is attested to by a supplier or vendor.
To generate an SBOM, navigate to Products, select view images from the bottom menu, and choose SBOM from the right-side menu. SBOM outputs can also be generated from within the dependencies tab of a product's findings.
### Key Features
Supported SBOM Formats
The platform supports widely adopted SBOM formats to ensure seamless integration and interoperability across security workflows:
* CycloneDX: A lightweight BOM standard optimized for security and supply chain use cases.
* SPDX (Software Package Data Exchange): A standardized and detailed format for sharing software metadata across tools and processes.
Export Capabilities
* Export SBOMs: The platform enables users to generate SBOMs in both CycloneDX and SPDX formats. This allows organizations to share, analyze, and distribute SBOMs as part of compliance, security, or validation workflows.
* Example: Export a CycloneDX SBOM post scan and compare the results to a vendor supplied SBOM.
## SBOM Use Cases
### Supply Chain Risk Assessment
Validate the integrity and security of third-party software components
* Example: An SBOM output reveals that a third-party library in an IoT firmware is not only out of date, but is associated with several critical vulnerabilities. This prompts the security team to review mitigation steps
### Regulatory Compliance Assurance
Use the SBOM to demonstrate adherence to industry standards and regulatory requirements.
* Example: From an internally written tool binary, an SBOM is generated in SPDX format to prove compliance with the EU Cyber Resilience Act during a 3rd party audit.
### Identification of unattested to components
Leverage SBOM’s to expose what is truly contained within third-party packages.
* Example: An SBOM reveals the presence of a compression library that was not attested to, or present within the vendor supplied SBOM.
### Incident Response Support
Use SBOM data to accelerate incident investigation and root cause analysis.
* Example: An SBOM helps CIRT members identify a compromised third-party library present within an analyzed binary, speeding up containment and resolution during a security investigation.
## Programmatic Access
Generate SBOMs programmatically using the Binarly API:
* [SBOM Report API](/api-reference/report/sbom-report) - Endpoint reference
* [Compliance Artifacts](/api-reference/use-cases/compliance-artifacts) - Automation scripts
# VEX (Vulnerability Exploitability Exchange)
Source: https://docs.binarly.io/user-guides/export/vex
The Binary Transparency Platform supports Vulnerability Exploitability Exchange
(VEX) formats CycloneDX and OpenVEX. VEX is a
[specification](https://www.cisa.gov/sites/default/files/2023-04/minimum-requirements-for-vex-508c.pdf)
published by CISA that defines requirements for formats to exchange statements
about vulnerabilities and products. Binarly's VEX export is accessed through the
report interface on the product overview and image overview pages.
# Key Features
The Transparency Platform's VEX report includes all vulnerabilities detected in
one product's image. The statements include the vulnerability's unique
identifiers, description, its status in BTP and the affected dependency's CPE
identifier.
The following is a single VEX statement in OpenVEX as it's exported from
Binarly.
```json vex-open-vex-example-file.json icon=braces theme={null}
{
"vulnerability": {
"name": "CVE-2007-2768",
"description": "OpenSSH, when using OPIE (One-Time Passwords in Everything) for PAM, allows remote attackers to determine the existence of certain user accounts, which displays a different response if the user account exists and is configured to use one-time passwords (OTP), a similar issue to CVE-2007-2243.",
"aliases": [
"GHSA-7c33-39g7-9rjm"
]
},
"products": [
{
"identifiers": {
"cpe23": "cpe:2.3:a:openbsd:openssh:10.0p2:*:*:*:*:*:*:*"
}
}
],
"status": "under_investigation"
}
```
VEX statements consist of a vulnerability description, optional identifier,
the vulnerability's remediation status, the affected product and a timestamp.
Thus, a VEX statement asserts that a product had a particular vulnerability with
a particular remediation status at a particular time. Multiple statements with the
same vulnerability and product can exist with different timestamps to describe
the timeline of remediation work being done on a vulnerability.
The Binarly Transparency Platform can export VEX statements as OpenVEX or
CycloneDX formatted files.
The **CycloneDX format** is a comprehensive standard for the software supply
chain. It defines a bill of materials that covers software, hardware, services,
cryptographic material, machine learning models and other types of assets. A
CycloneDX BOM can also contain VEX statements for the software it includes.
Choosing CycloneDX as export format will produce a SBOM with embedded VEX
statements as one standalone file.
In contrast, the **OpenVEX format** is a lightweight, embeddable
implementation of the VEX standard. It's purpose-built for VEX statements and
does not contain any non-VEX information. It's composable and can cover
multiple products or systems.
VEX reports can be requested from the product view's image list: in the image's
context menu (reachable via the three dots on the right). From the context menu,
selecting the desired VEX format will start the download of the report (see
below).
![VEX options in the image context menu.]()
# Use Cases
## Incident Response
VEX reports can be used to rapidly find products that contain components that
are vulnerable to newly discovered vulnerabilities. CERT members can use the
VEX reporting capability of the Binarly Transparency Platform to acquire
vulnerability remediation statuses for products.
## Third Party Compliance Reporting
OpenVEX and CycloneDX are open formats that can be used to exchange technical
compliance statements with third parties. A VEX report can substantiate claims
about up-to-date dependencies and vulnerability remediation efforts.
## System or Fleet-wide Risk Assessment
VEX reports are composable and can be combined to provide a global view of a
larger system. Individual components' images are uploaded to the Binarly
Transparency Platform, scanned and their VEX reports combined to help assessment
of system level risk.
# First Scan
Source: https://docs.binarly.io/user-guides/get-started/first-scan
Running your first scan with the Binary Transparency Platform is simple and fast. You can upload a variety of binary file types directly into the platform for analysis—most scans complete within a few minutes.
Uploads are organized into products, which work like folders or containers for related image versions. Think of a product as a collection of scans for a particular firmware or binary over time. You’ll find more on that in the Products section.
The diagram below shows the basic flow and the simple steps to run your first scan.
![First Scan Pn]()
### Here’s a quick walkthrough to get started:
![Firstscan3 Pn]()
1. **Find the Upload Button**\
From the dashboard, look in the bottom-left corner for the green upload arrow. Clicking it opens the upload dialog.
2. **Create a Product**\
Give your product a clear, descriptive name. Then click **Create** to make the container for your image.
3. **Add Your Binary**\
Drag and drop your binary file into the dialog—or browse to it manually. You’ll also have the option to label this as a new version, which helps track changes over time.
4. **Upload**\
Once your file is selected and versioned (optional), click **Upload**.
Upload speed depends on file size. Don’t close your browser during the upload process.
### **What Happens Next**
After uploading, the scan will enter a **processing** or **in progress** state. For small files, this usually takes 2–3 minutes. Larger files—like containers, embedded OS images, or full kernel binaries—might take 30 minutes or more.
You can track progress from the **Scans** menu.
### **Viewing the Results**
When processing is done, your scan will show as **finished**. Here's how to view the findings:
1. In the **Products** grid, click the product you just created.
2. Select the completed image scan.
3. You’ll land on the **Image Dashboard**, where you’ll see high-level findings from the binary analysis.
![Firstscan4 Pn]()
\
From there, you can:
* Navigate through sections of the report
* Use interactive graphs to drill down
* Filter, sort, and export data
* Share or take action on specific results
If you're ready to go deeper, check out the **Diving into Findings** section for a breakdown of everything in the scan results.
# Remediate Vulnerabilities
Source: https://docs.binarly.io/user-guides/get-started/fix-unknown
We're going to discover and fix a potential 0-day using the BTP platform. As an example, we're going to use a UEFI SMM driver that is vulnerable to an arbitrary code execution bug. The code is available to follow along.
## Preparing the example
Our test case is a UEFI driver that stores arbitrary data in SMRAM but has a fatal flaw that allows an attacker to trick SMM into executing any function. The driver consists of two files: `ExampleSmmStore.c`, and `ExampleSmmStore.inf`. To build a UEFI image with the driver inside, we'll need EDK II and then add a new folder with the driver's code to the OVMF package. First, clone the edk2 repository from GitHub and copy the driver's files into a new folder like this:
Check your operating system and install the required [tools](https://github.com/tianocore/tianocore.github.io/wiki/Getting-Started-with-EDK-II).
```bash theme={null}
git clone --recurse-submodules https://github.com/tianocore/edk2.git
```
```bash theme={null}
cd edk2 && source edksetup.sh && make -C BaseTools
```
```bash theme={null}
mkdir OvmfPkg/ExampleSmmStore
```
Create a new file named `ExampleSmmStore.c` in the `OvmfPkg/ExampleSmmStore` directory.
```c theme={null}
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
// EFI_EXAMPLE_SMM_STORE_SMM_COMMUNICATION_GUID =
// 22868f89-7cb2-4e90-b4ac-5582532135a9
EFI_GUID gEfiExampleSmmStoreCommunicationGuid = {
0x22868f89,
0x7cb2,
0x4e90,
{0xb4, 0xac, 0x55, 0x82, 0x53, 0x21, 0x35, 0xa9}};
VOID *gBuffer = NULL;
EFI_STATUS
EFIAPI
ExampleSmmStoreHandler(IN EFI_HANDLE DispatchHandle,
IN CONST VOID *Context OPTIONAL,
IN OUT VOID *CommBuffer OPTIONAL,
IN OUT UINTN *CommBufferSize OPTIONAL) {
EFI_STATUS Status;
//
// If input is invalid, stop processing this SMI
//
if ((CommBuffer == NULL) || (CommBufferSize == NULL) ||
(*CommBufferSize == 0)) {
return EFI_SUCCESS;
}
if (gBuffer) {
Status = gBS->FreePool(gBuffer);
if (EFI_ERROR(Status)) {
DebugPrint(DEBUG_INFO, "Failed to free buffer\n");
return Status;
}
gBuffer = NULL;
}
Status =
gBS->AllocatePool(EfiBootServicesData, *CommBufferSize, (VOID *)&gBuffer);
if (EFI_ERROR(Status)) {
DebugPrint(DEBUG_INFO, "Failed to allocate buffer\n");
return Status;
}
CopyMem(gBuffer, CommBuffer, *CommBufferSize);
return EFI_SUCCESS;
}
EFI_STATUS
EFIAPI
ExampleSmmStoreEntryPoint(IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable) {
EFI_STATUS Status;
EFI_HANDLE DispatchHandle;
//
// Register ExampleSmmStore communication handler
//
Status = gMmst->MmiHandlerRegister(ExampleSmmStoreHandler,
&gEfiExampleSmmStoreCommunicationGuid,
&DispatchHandle);
ASSERT_EFI_ERROR(Status);
if (EFI_ERROR(Status)) {
DEBUG((DEBUG_ERROR, "Failed to register ExampleSmmStoreHandler: %r!\n",
Status));
}
return Status;
}
```
Create a new file named `ExampleSmmStore.inf` in the `OvmfPkg/ExampleSmmStore` directory.
```
[Defines]
INF_VERSION = 0x00010005
BASE_NAME = ExampleSmmStore
FILE_GUID = E56DDE0D-F510-40E1-A575-201B9BA81D1F
MODULE_TYPE = DXE_SMM_DRIVER
VERSION_STRING = 1.0
ENTRY_POINT = ExampleSmmStoreEntryPoint
PI_SPECIFICATION_VERSION = 0x00010400
[Sources]
ExampleSmmStore.c
[Packages]
MdeModulePkg/MdeModulePkg.dec
MdePkg/MdePkg.dec
OvmfPkg/OvmfPkg.dec
[LibraryClasses]
MmServicesTableLib
SmmMemLib
UefiDriverEntryPoint
UefiLib
[Protocols]
gEfiSmmCpuProtocolGuid
gEfiSmmSwDispatch2ProtocolGuid
gEfiSmmVariableProtocolGuid
[Depex]
TRUE
```
The driver needs to be added to the OVMF package by adding the following line to `OvmfPkg/OvmfPkgX64.fdf` file in the \[FV.DXEFV] section.
```c theme={null}
INF OvmfPkg/ExampleSmmStore/ExampleSmmStore.inf
```
And the following line to the end of the file: `OvmfPkg/OvmfPkgX64.dsc`.
```c theme={null}
OvmfPkg/ExampleSmmStore/ExampleSmmStore.inf {
DebugLib|OvmfPkg/Library/PlatformDebugLibIoPort/PlatformDebugLibIoPort.inf
MemoryAllocationLib|MdePkg/Library/UefiMemoryAllocationLib/UefiMemoryAllocationLib.inf
}
```
Now we're ready to build the UEFI image with debugging symbols.
```bash theme={null}
build -p OvmfPkg/OvmfPkgX64.dsc -a X64 -t CLANGPDB -b DEBUG -D SMM_REQUIRE
```
After the build process is done, the firmware image will be at
**Build/OvmfX64/DEBUG\_CLANGPDB/FV/OVMF.fd**
```bash theme={null}
mkdir -p pdb_files && find Build -name "*.pdb" -type f -exec cp -f {} pdb_files/ \;
```
## Let's investigate the example
First, let's upload the firmware image to a product so we can investigate the image. Click on the **"Upload"** dialog in the product's interface. Choose our previous compiled OVMF.fd to upload, set an image name and version number. At the end hit the **"Upload"** button.
![Screenshot of the image upload modal]()
### Upload the debug symbols
Before we get Started, we need to upload the debug symbols for the firmware image to identify the vulnerable function. Checkout the [Upload Debug Symbols](/resource-center/debugging-symbols) guide for more information.
### Investigate the finding
In the image findings tab should be two findings with the title SMM Arbitrary Code Execution in the ExampleSmmStore component. Clicking the first and navigating to the Details tab will reveal the decompiled code of the vulnerable function with the offending lines highlighted in red.
![Screenshot showing an excerpt of the image's findings.]()
The highlighted lines are accompanied by comments explaining the technical details of the issue: The driver's SMI handler, which runs in SMM, uses the `AllocatePool` and `FreePool` functions from the UEFI Boot Services. Because the Boot Services code is outside of SMRAM, an attacker can replace it with their own and then call the SMI handler to trick it into executing it.
We'll ask the Binarly Transparency Platform's built-in AI assistant to help us fix the issue now by clicking the bottom right button to open a new chat window.
![]()
The chat window has one suggestion to analyze the vulnerable code, so we'll go with that one. AI assistant will reply with a description of the vulnerability contextualized by the decompiled code as well as a detailed breakdown of how to fix the issue. It correctly points out that using Boot Services in SMM is dangerous and that we should replace them with the SMM-equivalents provided by the `EFI_SMM_SYSTEM_TABLE`. AI assistant will produce a fixed variant of the decompiled code (see below).
```c theme={null}
EFI_STATUS
EFIAPI
ExampleSmmStoreHandler(IN EFI_HANDLE DispatchHandle,
IN CONST VOID *Context OPTIONAL,
IN OUT VOID *CommBuffer OPTIONAL,
IN OUT UINTN *CommBufferSize OPTIONAL) {
EFI_STATUS Status;
//
// If input is invalid, stop processing this SMI
//
if ((CommBuffer == NULL) || (CommBufferSize == NULL) || (*CommBufferSize == 0)) {
return EFI_SUCCESS;
}
if (gBuffer) {
Status = gBS->FreePool(gBuffer); // [!code --]
Status = gSmst->MmFreePool(gBuffer); // [!code ++]
if (EFI_ERROR(Status)) {
DebugPrint(DEBUG_INFO, "Failed to free buffer\n");
return Status;
}
gBuffer = NULL;
}
Status = gBS->AllocatePool(EfiBootServicesData, *CommBufferSize, (VOID *)&gBuffer); // [!code --]
Status = gSmst->MmAllocatePool(EfiBootServicesData, *CommBufferSize, (VOID *)&gBuffer); // [!code ++]
if (EFI_ERROR(Status)) {
DebugPrint(DEBUG_INFO, "Failed to allocate buffer\n");
return Status;
}
CopyMem(gBuffer, CommBuffer, *CommBufferSize);
return EFI_SUCCESS;
}
```
We can now go back to the driver and apply the fix AI assistant created for us. In `ExampleSmmStore.c` we're going to replace the usage of `gBS` with `gSmst` in lines 53 and 62. In the newest version of Tianocore these functions got unified under the MM framework and make use of the new function names `MmFreePool` and `MmAllocatePool`. Now we need to recompile the fixed code with the following snippet.
```bash theme={null}
build -p OvmfPkg/OvmfPkgX64.dsc -a X64 -t CLANGPDB -b DEBUG -D SMM_REQUIRE
```
After uploading the fixed version and waiting for the scan to finish, we'll notice that this image has two issues less. We'll be using the image comparison function to verify the two SMM vulnerabilities are gone. To do this, select the checkboxes left of the vulnerable and fixed images, then click the Compare button at the top of the section.
![Screenshot showing the selection of the vulnerable and fixed firmware images using checkboxes in the Binarly Transparency Platform UI before comparison.]()
On the compare view, make sure the fixed image is on the right and the vulnerable image is on the left. If this is not the case, the comparison results will be inverted. To swap the right and left images, click the Swap button between both. Once the comparison direction is correct, we can see that both SMM Arbitrary Code Execution vulnerabilities are no longer found in the fixed image.
![Screenshot of the comparison view in the Binarly Transparency Platform, indicating that SMM Arbitrary Code Execution vulnerabilities have been resolved in the fixed firmware image.]()
# Glossary
Source: https://docs.binarly.io/user-guides/get-started/glossary
This section defines key technical terms used throughout the Binarly Transparency Platform documentation, with practical examples to demonstrate their application.
**Algorithm Compliance**
* Definition: The classification of a detected cryptographic algorithm as current, deprecated, weak, or quantum-vulnerable. Active compliance reporting is scoped to NIST IR 8547 (post-quantum cryptography); weak and deprecated classifications are informational, derived from industry consensus.
* Example: The platform flags an MD5 hash function as deprecated and an RSA signing key as quantum-vulnerable, providing compliance context alongside each finding.
**API (Application Programming Interface)**
* Definition: A set of endpoints and tools allowing external applications or systems to communicate programmatically with the Binarly Transparency Platform.
* Example: A development team uses the API to automate binary uploads and fetch vulnerability results within their CI/CD pipeline, reducing manual efforts and ensuring timely security assessments.
**Binary Image**
* Definition: A machine-readable file representing compiled firmware, software, or containerized environments. The platform analyzes binary images to detect vulnerabilities, misconfigurations, and malicious code.
* Example: A firmware engineer uploads a .bin file for a router to the platform, which scans and identifies a critical vulnerability in a specific module.
**CBOM (Cryptographic Bill of Materials)**
* Definition: A structured inventory of all cryptographic materials - algorithms, protocols, certificates, and keys - discovered within a scanned binary image, exported in CycloneDX JSON format.
* Example: After scanning a firmware image, the platform generates a CBOM documenting every cryptographic algorithm and certificate found across all components, enabling a compliance review against NIST standards.
**CI/CD (Continuous Integration/Continuous Delivery)**
* Definition: A software development practice that automates code integration, testing, and delivery. Integrating the Binarly Platform into a CI/CD pipeline ensures security scans occur automatically with each software build.
* Example: A development team configures Jenkins to upload compiled binaries to the platform, enabling automated vulnerability scans before deployment.
**Cryptographic Material**
* Definition: Algorithms, protocols, certificates, and cryptographic keys detected within a binary image during static analysis. The Binarly Transparency Platform surfaces these as a dedicated finding type in the Cryptographic Materials tab.
* Example: A scan of a router firmware image reveals embedded RSA-1024 keys, an expired X.509 certificate, and usage of MD5 - all cataloged as cryptographic material findings.
**CycloneDX**
* Definition: A standardized, lightweight SBOM (Software Bill of Materials) format for software security and supply chain transparency.
* Example: After analyzing a firmware image, the platform generates a CycloneDX SBOM to document all software components. This enables the enterprise to track vulnerabilities in specific libraries.
**Dependency Analysis**
* Definition: Identifying and analyzing software components, including direct and transitive dependencies, to detect vulnerabilities or risks.
* Example: A supply chain manager uses the platform to identify hidden dependencies in IoT device firmware that were not declared in the vendor-provided SBOM.
**Firmware**
* Definition: Low-level software that provides essential functionality for hardware devices, such as servers, routers, and IoT systems. Firmware operates as the interface between hardware and higher-level software.
* Example: Using the platform, a security analyst scans a server’s BIOS firmware and identifies configuration weaknesses that could allow unauthorized bootloader access.
**GUID (Globally Unique Identifier)**
* Definition: A unique identifier referencing specific firmware modules or components within binary images.
* Example: When reviewing scan results, an analyst uses the GUID to pinpoint the firmware module containing a high-severity vulnerability.
**Malicious Code Detection**
* Definition: Identifying harmful or suspicious code embedded within binaries, such as malicious hooks, implants, or known threats.
* Example: The platform detects malicious implants hidden in a UEFI firmware image, highlighting the code’s location and functionality for immediate investigation.
**Mitigation Failure**
* Definition: A condition where a general coding best practice or security measure has not been applied or Secure by Design principles have not been implemented.
* Example: A firmware scan reveals that many binary functions do not leverage Stack Canaries or Control Flow.
**NIST IR 8547**
* Definition: A NIST Interagency Report defining the timeline and recommendations for transitioning from quantum-vulnerable cryptographic algorithms (such as RSA and ECDSA) to post-quantum cryptographic standards.
* Example: The platform's PQC Compliance Report references NIST IR 8547 to flag quantum-vulnerable algorithm usage and provide migration guidance aligned to short, mid, and long-term transition timelines.
**PQC (Post-Quantum Cryptography)**
* Definition: Cryptographic algorithms designed to be secure against attacks by quantum computers. NIST has standardized PQC algorithms including ML-DSA (CRYSTALS-Dilithium) and SLH-DSA (SPHINCS+) to replace quantum-vulnerable algorithms such as RSA and ECDSA.
* Example: A security team uses the platform's PQC Compliance Report to identify all instances of quantum-vulnerable RSA and ECDSA usage in firmware and plan migration to ML-DSA per NIST IR 8547 guidance.
**SBOM (Software Bill of Materials)**
* Definition: A detailed inventory of software components, libraries, and dependencies within a binary image. SBOMs enable organizations to understand the software composition of deployed packages within their environment.
Example: The platform generates an SBOM for a scanned firmware image, enabling the organization to verify all components and cross-check for vulnerable versions.
**SPDX (Software Package Data Exchange)**
* Definition: An open standard format for creating and sharing SBOMs, enabling consistent software components and metadata documentation.
* Example: After analyzing a firmware binary, the platform exports an SPDX-formatted SBOM that can be used in compliance reports.
**Stack Canary**
* Definition: A security mechanism that detects and prevents stack buffer overflow attacks. A canary value is placed between a function’s local variables and control data (e.g., return address) and validated before the function returns to detect tampering.
* Example: Before returning from a function, the system verifies the integrity of the stack canary. If the canary value has been altered, the program terminates to prevent exploitation.
**Supply Chain Security**
* Definition: The practice of validating software components and ensuring they are free from risks introduced through third-party suppliers.
* Example: An organization uses the platform to validate third-party firmware for IoT sensors, uncovering undocumented components and hidden vulnerabilities.
**Transitive Dependencies**
* Definition: Software components that are not directly included but are brought into a project by other dependencies.
* Example: During analysis, the platform identified a vulnerable transitive dependency within a firmware library not listed in the original SBOM.
**UEFI (Unified Extensible Firmware Interface)**
* Definition: A modern firmware standard that replaces the legacy BIOS, providing advanced boot capabilities and security features.
* Example: The platform scans UEFI firmware and detects a memory corruption vulnerability in an SMM (System Management Mode) handler, requiring immediate remediation.
**Vulnerability Analysis**
* Definition: The process of detecting, classifying, and assessing security weaknesses within binary images based on severity and potential impact.
Example: A firmware scan reports vulnerabilities with detailed CVSS scores, descriptions, and remediation guidance, allowing engineers to prioritize fixes.
**Zero-Day Vulnerability**
* Definition: A security flaw unknown to the vendor and does not yet have a patch, making it highly exploitable.
* Example: The platform detects an unknown vulnerability in an IoT firmware module, enabling the security team to address it before exploitation occurs.
# Login
Source: https://docs.binarly.io/user-guides/get-started/login
The Binarly Transparency Platform is a subscription-based SaaS platform that is purpose-built to protect manufacturers and enterprises from firmware and supply chain threats. It can be implemented as a critical feed into a well-defined security program (SOC), as part of a continuous integration/ continuous delivery (CI/CD) manufacturing program, OEM, or as a standalone binary visibility and vulnerability management tool for enterprises.
The Platform is powered by thoughtful design, proprietary deep code inspection, machine learning, and advanced decision-flow algorithms. Binarly technologies, paired with unprecedented security research and industry expertise, afford customers world-class known and unknown vulnerability detection, visibility, and actionable data outputs previously unavailable.
The Binarly Transparency Platform is hosted in the cloud and provisioned for each customer, creating an individual container where all customer data is securely stored. Data is sent to the Platform over an authenticated and encrypted SSL channel.![]()
### Authenticating to the Platform
Access your private platform instance by navigating to the URL provided:
[https://dashboard-MASKED.binarly.cloud/](about:blank) Where MASKED would be your individual assigned instance name. This is a randomly generated URL to ensure security. We recommend creating a browser bookmark for ease of use.
You will be redirected to the authentication provider page, where you can log in using your email. Accounts will be provisioned along with the dashboard instance. These will be the primary points of contact and will be provided to your account team during onboarding. Adding additional accounts to the platform, can be performed by a user defined as an organization admin within the platform. Lost passwords and password resets can be performed by clicking the “Forgot password” link, contacting your organization admin, or simply by opening a ticket with the Binarly support team.
By default, Multi-Factor Authentication and strong passwords are enforced. You will be prompted to configure this on your initial login. The platform will work with almost any multi-factor authentication application. Microsoft and Google Authenticator applications are popular choices.
> To configure Multi-Factor Authentication (MFA):
1. Download an authenticator app such as Google Authenticator or Microsoft Authenticator on your mobile device.
2. Scan the QR code displayed during the initial login.
3. Enter the generated code to complete the MFA setup.
> Note: If you face issues during setup, refer to the authenticator app’s user guide or contact Binarly Support.
### Password Policy
The minimum password length for SaaS instances of the Binary Transparency Platform is 32 characters. Passwords must also meet complexity requirements, including at least one capital, alphanumeric, and special character. Due to these complex requirements, we strongly recommend utilizing a password vaulting solution and randomly generated passwords rather than manually entering strong passwords.
### Workflows
The Binarly Transparency Platform provides workflows designed specifically for user personas and functional applications of the solution. Common users include supply chain security teams, third-party vendor evaluators, firmware/BIOS developers, OEMs, and ODMs. These users typically utilize one of two primary workflows: project-based or validation (scan)-based. Automation capabilities are extensively employed in software development life cycles (SDLC) and Continuous Integration/Continuous Deployment (CI/CD) pipeline applications of the solution.
In a project-based workflow, an OEM or device manufacturer typically incorporates the platform as part of their release validation process. This ensures that final compiled binaries are free of vulnerabilities prior to the release of software packages or updates. With its robust, REST API-based architecture, the Binarly Transparency Platform can seamlessly integrate into existing development or quality assurance workflows, offering flexibility and scalability.
In a software supply chain or third-party vendor validation workflow, any third-party binaries can be submitted to the platform for assessment. This process provides deep insights into the contents and vulnerability posture of software at levels typically unattainable without source code access. The platform enables critical visibility into issues within components, dependencies (both static and transitive), cryptographic materials, embedded secrets, and adherence to secure-by-design principles. These capabilities ensure that vulnerabilities in binaries, whether currently deployed or being integrated into enterprise infrastructure, products, or environments, are identified and mitigated effectively.
### Platform Components
The Binarly Transparency Platform is organized into logical components that follow a clear and intuitive flow. This design ensures that users—whether analysts, administrators, or executives—can easily access the specific information relevant to their roles and use cases.
Key Features of the Platform Components
1. User-Centric Design:
* Tailored to different personas, providing role-specific data and insights:
* Analysts: In-depth vulnerability and threat details.
* Administrators: Configuration and management tools.
* Executives: High-level overviews and trend analysis.
2. Default Dashboard View:
* Upon login, users are presented with a cumulative dashboard, offering an aggregated overview of all data assessed by the platform.
* This dashboard acts as a central hub, summarizing key metrics, findings, and trends across the entire environment.
3. Logical Flow:
* The platform is structured to guide users seamlessly through workflows, ensuring they can efficiently analyze, prioritize, and act on findings.
# Requirements
Source: https://docs.binarly.io/user-guides/get-started/requirements
Upon purchasing the platform, you will receive access credentials and details for your dedicated cloud tenant. All communication with the platform is encrypted using SSL, ensuring data security.
### Initial Setup
1. Provisioning: Your tenant will be pre-configured and assigned to the primary customer contact(s).
2. Credentials: Secure credentials and instructions will be shared via an invitation email.
3. API Integration: REST APIs are supported for automation and integration. Swagger documentation is available for API implementation.
### System Requirements
Ensure that the systems interfacing with the platform meet the following:
* Modern web browser (e.g., Chrome, Edge, Firefox).
* Multi-factor authentication application (e.g., Google Authenticator, Microsoft Authenticator).
A password vault is recommended for managing strong passwords.
# Reviewing findings, images, and product trends
Source: https://docs.binarly.io/user-guides/image-scans/all-about-details
Organize images by product, review analysis findings, and track vulnerability trends over time in the Binarly Transparency Platform.
Once a product is created, it can serve as a container for related images or successive versions of analyzed binaries. This organization facilitates streamlined analysis and review of vulnerabilities or configuration issues.
### Uploading and Organizing Images
1. Image Upload:
* Images can be added to a product either during its creation or later via the Upload Image option.
* Products are designed to track images by version. Proper trending and analysis comparisons by version are dependent on this structure. Although products c\_an\_ accommodate an unlimited number of different images, for optimal operation of the Product you MUST:
* Group similar images or related versions within the same product.
* Separate dissimilar images into distinct products for better organization and analysis clarity.
2. Recommendations for Organization:
* Use consistent naming conventions for products and associated images to maintain a logical structure.
* Ensure that each product contains only related images to simplify analysis and reporting.
### Viewing Images in a Product
1. Accessing Images:
* Navigate to the desired product to view its uploaded images.
* The list of images associated with the product will display in the grid view.
2. Processing Status:
* After an image is uploaded or submitted via the API, it will initially show a "Processing" status while the platform analyzes the binary.
* Once the analysis is complete:
* The file name will be displayed in purple text.
* The number of findings associated with the image will also appear in the grid.
3. Detailed Findings:
* Click on the file name (purple text) to view a comprehensive list of findings for the analyzed binary.
* This detailed view provides insight into vulnerabilities, misconfigurations, and other issues identified during the analysis.
### Benefits of Viewing Images by Product
* Provides a consolidated view of all analyzed binaries within a logical grouping.
* Enables efficient navigation between images and their findings for detailed review and remediation planning.
* Facilitates tracking and management of multiple versions or updates of the same firmware or software.
This structured approach to viewing and organizing images ensures users can efficiently manage data and focus on actionable insights.
## Trending
Trending provides a graphical representation of issues identified over time for a selected product. This visualization helps users track the evolution of vulnerabilities, misconfigurations, or other findings, offering a clear visual summary of changes based on new scans.
#### Key Features of the Trending Graph
1. Issues Over Time:
* Displays trends in findings categorized by age and severity.
* Highlights the progression of issues, including new discoveries and resolved items.
2. Customizable Date Ranges:
* Users can adjust the date range to focus on specific timeframes of interest.
* This flexibility allows for targeted insights into historical patterns or recent developments.
3. Visual Summaries:
* Offers an at-a-glance overview of the product's security posture and its changes over time.
* Identifies spikes or reductions in findings, aiding in prioritization and decision-making.
#### Benefits of the Trending Feature
* Actionable Insights:
* Helps prioritize remediation efforts by highlighting trends in critical or high-severity findings.
* Historical Context:
* Provides a historical perspective on the product’s security, enabling better understanding of long-term risks.
* Customization:
* Allows users to tailor the view to meet specific needs, whether for reporting, analysis, or planning.
## Latest Scan
The Latest Scan feature tags the most recent analysis of a product as "Latest" and ensures its results are prominently reported in both the primary and product-specific dashboards. This feature provides a comparative view, allowing users to monitor changes and assess progress across different versions of the same binaries.
#### Key Features of the Latest Scan
1. Comparative Analysis:
* Visibility into differences between versions of the same binaries, showing improvements, new findings, or regressions.
* Provides insights into how updates or patches have impacted the security posture.
2. Dashboards Visibility :
* Results from the latest scan are displayed on:
* The primary dashboard, offering a high-level overview of all products.
* The product-specific dashboard, focusing on granular details for that product.
3. Third-Party Supply Chain Validation:
* Confirms that updated binaries address previously identified issues.
* Offers visibility into potential new issues or regressions introduced in the latest version.
4. OEMs and Software Vendor Use Cases:
* Demonstrates improvements in code quality and security measures addressing vulnerabilities.
* Validates that updates meet the security and compliance requirements of end-users or partners.
#### Benefits of the Latest Scan
* Improved Monitoring:
* Enables continuous tracking of a product’s security posture over successive scans.
* Actionable Insights:
* Helps OEMs, software vendors, and supply chain partners prioritize further remediation or development efforts.
The Latest Scan feature is a vital tool for maintaining transparency, validating improvements, and ensuring the security and reliability of binaries over time.
### Upload Image (Plus Icon)
With a product selected, images can be uploaded by clicking the plus icon in the lower right section of the grid view. This action automatically associates the uploaded image with the selected product. Once the upload dialog appears, you can drag and drop the file or navigate to it on your machine.
![]()
The dialog also states the code size above which components are excluded from analysis, so you know before uploading what the analysis covers. Components over that size are still inventoried, and they are listed on the image afterwards under [Reduced analysis coverage](#components-tab).
![Upload dialog with a notice reading Components with code size greater than 200 MB are excluded from analysis.]()
An upload progress dialog appears in the lower right of the interface. Upon completion, the image will begin processing, with times varying based on file type, size, and complexity. During processing, a spinning circle and an “In Progress” message will appear. Active scans can be monitored from the product view or via the scans menu, which is covered in another section. When the scan is completed, findings and severity details will populate, preparing the results for review.
![]()
## Fields
#### Fields in the Images Grid
The Images Grid provides detailed data about analyzed images, organized into columns. Each column heading offers options to sort and filter, enabling efficient navigation—particularly useful for tracking multiple image versions within a product.
#### Key Fields
1. Name:
* Displays the file name of the uploaded image.
* After analysis completion, the name becomes clickable, providing access to a detailed overview of the results.
2. Findings:
* Shows the total number of findings identified in the analyzed image.
* Excludes mitigations and weaknesses to focus on actionable issues.
3. Severity:
* Categorizes findings by severity level:
* Critical, High, Medium, Low, and Unspecified.
* Provides counts for each category, helping users prioritize issues.
4. Scanned and Uploaded:
* Displays two timestamps:
* Uploaded: When the image was submitted.
* Scanned: When the analysis was completed.
5. Created By:
* Identifies the user who uploaded the image and initiated its scan, offering accountability.
6. Feature Tags:
* Highlights the features available for the image, such as:
* Reports: JSON and PDF analysis summaries.
* SBOM: Software Bill of Materials.
* CBOM: Cryptographic Bill of Materials.
7. Action Menu:
* Provides follow-up options for the analyzed image, including:
* Rescan the image.
* Adding Debug Information/Symbols.
* Generating Reports (e.g., PDF, JSON).
* Downloading the image file, SBOM, or CBOM.
* Archiving the image for better workspace organization.
Benefits
* Efficient Navigation: Sorting and filtering options simplify image tracking and review.
* Detailed Insights: Provides quick access to findings and severity breakdowns for informed decision-making.
* Streamlined Workflow: The action menu enhances usability, enabling fast execution of key tasks like rescanning or generating reports.
## Viewing image details
Products are created to organize and house images assessed by the platform. Images can be uploaded directly to the platform from the actions menus discussed above or from an API call run from a command line, CI pipeline, or other automated mechanism. Please see the API documentation and use cases guide for information about leveraging the API.
Once an image is selected from the product View, it will present all information about the findings discovered during the scan of the selected image. This image-specific view serves as a primary interface to view the details of the various finding types, assess and prioritize actions to be taken, and better understand the overall risk associated with a specific image scan.
#### Image Overview (Product Specific Dashboard)
The image overview serves as a heads-up display and summary review of the findings discovered within the analyzed image. Tabbed navigation to the different finding types and categories, as well as interactive graphical displays of the findings, are available to help aid understanding of the analysis and Provide easy navigation to specific areas of Interest or most critical findings.
![Dash1 Pn]()
**Tabbed views**
Findings—Your primary view to review finding details provides a highly customizable grid view. You can quickly sort, filter, and prioritize the different findings. Findings can be drilled into for extended information.
Cryptographic materials—This view isolates cryptographic findings. It provides insights into discovered and potentially problematic keys, algorithms, and certificates.
Secrets - The secrets tab will reveal sensitive information discovered within the binary. This includes API credentials, encryption keys, JSON web tokens, webhooks, and other sensitive details.
Secure by Design: This section covers issues related to CISA’s Secure by Design principles and the NIST SP 800-218 Secure Software Development Framework. It highlights where current practices deviate from recommended security standards in coding and points out missed opportunities to build and ship more secure software.
Dependencies- Dependencies provide a detailed grid View of the dependency findings organized by the individual dependency. This provides an efficient presentation of the findings by Dependency, including relationship and impacted components.
Components- This tab lists all components discovered within the assessed binary in a Tree View.
History—This view details the history of the image scan, including the name, Scan Timeframes, who scanned it, and any other activities, such as rescans.
**Image Information Blocks**
![]()
Image- Full file name of the image uploaded with the ability to download a copy of the image from the platform to a local device
Attached symbols—This allows you to attach debug information or symbols (PDB Files). When debug symbols are provided (a rescan of the image is triggered on upload), they can enhance the decompiled pseudocode representation of vulnerabilities, presenting more precise details.
![]()
Scanned—This provides a date and time stamp for when the platform completely and fully processed the image scan.
Uploaded- This provides a date and time stamp for when the image upload to the platform was completed. The delta between uploaded and scanned values is the duration of the scan.
## Interactive dashboard graphs ( Product specific)
![]()
**Priority Findings**
This graph details the high, critical, and medium severity findings across all products and images. It is designed to highlight the most pressing issues for investigation or remediation. The areas of the graph are Interactive and can be used to sort or drill directly into a filtered binding page detailing the graphed data.
**Critical Unknown Findings**
This graph details and lists only unknown vulnerabilities discovered across all products and images. The graph is sorted by class of vulnerabilities, such as DXE Memory Corruption or SMM Memory Content Disclosure. Listed within these classes are the discovered unknown vulnerabilities. Unknown vulnerabilities are all classified as critical severity findings as they have not been previously seen before and are technically zero-day. Drilling down any portion of the graph will take you to a filtered list of the findings sorted by only unknown finding type.
**Finding Types**
The finding types are crucial to understanding the vulnerabilities and issues discovered and how many exist within each finding category. This graph can serve as a quick view to understand where the vulnerabilities and problems exist within this image. With this information, an analyst can go directly to the associated tab, where many issues are preset, or a specific category of findings may be of interest or concern. Drilling down in the graph will take you to a filtered View in the findings tab filtered by the selected issue type.
**Unreviewed findings**
The platform supports Triaging and tagging specific issues within the findings grid. This is designed to help ensure the most critical findings are tracked and appropriate actions are taken. It provides a means to assess what has quickly and has yet to be reviewed by an analyst or user of the platform. Status settings include New, In progress, Rejected, and Remediated. This graph provides a glance at the issue status from the Assessed Binary. The unreviewed findings graph does not support drill down and is only offered as an informational representation.
**Vulnerable External Dependencies**
The vulnerable external dependencies graph represents a high-level overview of the statically linked and transitive dependencies discovered within the images analyzed by the platform. This important representation provides visibility of the proper dependencies and components that make up the firmware, Linux packages, or containers analyzed by the platform. Hovering specific dependency names will provide visualizations of the versioning and counts of this particular dependency. Given this potentially large number of identified Dependencies, details are available within each image under the dependencies tab.
**Findings Tab**
The Findings tab within a product is one of the most accessed sections. It provides a comprehensive grid view with highly customizable columns. This layout supports advanced searching, filtering, and sorting capabilities, enabling users to efficiently review, prioritize, and manage finding data and details.
**Columns**
The findings grid is organized into columns, each detailing specific aspects of individual findings to aid in data consumption, prioritization, and action planning. All columns support searching, sorting, and filtering, with additional customization options to select and lock specific columns, ensuring a tailored view for enhanced usability.
**Sorting and Filtering**
Each column offers distinct sorting and filtering options based on the type of data it represents. For instance:
* The CVSS column includes a range-based filter to specify a range of scores.
* The Type column provides a pick-list menu with available options.
* The Finding column includes a free-form search box for text-based searches.
All columns support ascending and descending sorting, allowing users to refine their views further for efficient data analysis and action.
*Filter by CVSS score range* ![]()
\*Filter by Finding
\*![]()
### Filter Settings
You can configure column display settings through the Settings menu, accessible via the gear icon on the upper right of the grid. Selecting this icon opens the Column Selection menu, where you can customize the grid view to suit your preferences. Here, you can choose which columns to display in the grid view.
To fix a column to the left or right side of the grid, use the up and down arrows beside each column name. Additionally, you can reorder columns by dragging and dropping them to your preferred sequence. This allows you to effectively organize and prioritize the data view, optimizing your workflow's layout.
![]()
#### Filters Menu (Advanced Filtering)
As the platform processes an increasing volume of images and products, the associated datasets and findings can become extensive. To manage this complexity, creating customized datasets based on specific criteria is essential for efficiently searching and visualizing issues.
#### Overview of the Filters Menu
The Filters Menu, located in the upper-right corner of the interface, offers powerful tools for constructing complex filters. These filters enable users to apply a wide range of criteria across all data columns, allowing for the creation of tailored views that focus on specific findings or groups of findings.
#### Key Capabilities
* Custom Filtering: Apply filters to refine datasets based on severity, product type, date, vulnerability class, or other parameters.
* Multi-Criteria Filtering: Combine multiple filters to create highly specific datasets, enhancing the ability to identify and prioritize critical issues.
* Column-Specific Filters: Use column-level filtering to target findings relevant to your analysis.
#### Benefits
1. Efficient Data Management: Navigate and manage large datasets with ease, ensuring that key findings are not overlooked.
2. Focused Insights: Narrow down results to the most relevant issues, allowing for targeted remediation efforts.
3. Streamlined Exploration: Create customized views that simplify the analysis process and improve decision-making efficiency.
The advanced filtering capabilities of the Filters Menu provide users with a robust framework for managing extensive data, enabling effective exploration and prioritization of findings across multiple images and products.
### Finding Details
To access detailed information about a specific finding, click on any linked text or anywhere within the corresponding row in the Findings Grid. This action will open the detailed view for the selected finding, where the type of finding and available data determine the information displayed.
The finding details page displays reference information such as metrics from the [Common Vulnerability Scoring System](https://nvd.nist.gov/vuln-metrics/cvss) (CVSS), the [Exploit Prediction Scoring System](https://www.first.org/epss/) (EPSS), and the [Exploit Maturity Score](https://www.binarly.io/blog/the-hidden-danger-of-probabilistic-scoring-introducing-exploitation-maturity-score-ems) (EMS). It also shows confidence and reachability analysis to indicate the exploitability of the finding.
Classifications are provided using the [Common Weakness Enumeration](https://cwe.mitre.org/data/index.html) (CWE), [Mitre Adversarial Tactics, Techniques, and Common Knowledge](https://attack.mitre.org/) (ATT\&CK), and the [Malware Behavior Catalog](https://github.com/MBCProject/mbc-markdown) (MBC) ontologies. The page indicates whether the vulnerability is listed in CISA’s [Known Exploited Vulnerabilities Catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) (KEV) and whether it is known to be used in ransomware campaigns.
Additionally, the page lists vulnerability identifiers issued by the [Common Vulnerabilities and Exposures](https://www.cve.org/) (CVE) system, along with a description of the vulnerability, its impact, recommended actions, and links to proof-of-concept code, weaponized exploits, vendor announcements, and other references.
The page also provides a detailed breakdown of the component affected by the finding. Components may be files, UEFI modules, or PEI modules detected in the uploaded image. In addition to the component’s name and path inside the image, the finding details page shows its size, type, and type-specific information, such as an executable’s dynamic linker or a UEFI module’s GUID. If the component is a binary, information about the type of compilers used during the build process appears next to it. Multiple compilers or multiple versions of the same compiler may have contributed to the build, and the build environment section also includes the instruction set architecture and the operating system ecosystem of each compiler.
The finding details include the evidence, which delivers deep technical insights. Depending on the type of finding, this may be decompiled pseudocode, affected address ranges, or a structured representation of the offending artifact, such as a cryptographic asset’s key length, algorithm, and certificate validity.
If the affected component is part of a dependency, its product name, vendor, and detected version range are shown on the finding details page. If the issue indicated by the finding can be remediated by updating the dependency, the earliest safe version is also displayed alongside the dependency information.
The detailed view enables users to investigate findings effectively and provides the necessary context to prioritize remediation efforts. This granular insight supports a comprehensive understanding of vulnerabilities,their associated risks and mitigation actions to be considered.
### Finding Detail Options
Within a findings, options exist to afford users the ability to set a status or mark a specific finding with a label, create tickets using the built-in Integrations, and generate reports specific to that finding
## Set Status
The Set Status feature allows users to categorize a finding's progress or resolution state. These statuses are visible to all users and are reflected in the Unreviewed Findings graph on the product-specific dashboard. This functionality aids in tracking review progress and documenting decisions regarding specific findings within an image.
### Status Options
1. New:
* Default status for all findings that have not been reviewed or updated.
* Represents findings that require initial assessment.
2. In Progress:
* Indicates a finding is under active review, investigation, or remediation.
* Used when:
* The issue is being addressed in code.
* Mitigation efforts are underway by a third-party vendor.
3. Rejected:
* Marks findings that are:
* Determined to be false positives.
* Classified as non-threats (e.g., mitigated upstream or deemed unreachable).
* Commonly used when a finding does not require further action.
4. Remediated:
* Used for findings that have been successfully patched or mitigated.
* Represents a resolved issue with no further action required.
By setting the status of findings, users can enhance collaboration, maintain accurate records, and provide visibility into the review and remediation process for all stakeholders.
### Create Ticket
The Binarly Transparency Platform offers a built-in, Two way integration with Atlassian Jira, enabling seamless issue tracking and management. To use this feature, the Jira integration must be pre-configured via the Main Settings menu.
#### Configuring Jira Integration
For detailed instructions on configuring Jira integration, please refer to the Intergerations Section.
#### Using the "Create Ticket" Feature
Once the integration is set up, the Create Ticket option allows you to generate issues directly within your Jira system, leveraging the two-way integration capability.
Key functionality includes:
1. Issue Creation:
* Findings from the Transparency Platform can be forwarded as Jira issues.
* The integration automatically transfers finding details into the newly created Jira ticket.
2. Organizational Alignment:
* Tickets are created within your organization’s Jira project structure, ensuring alignment with existing workflows.
3. Visibility in the Binarly Transparency Platform:
* After a Jira ticket is created, the corresponding finding in the Transparency Platform will display the Jira ticket headline and a direct link to the Jira issue.
* This integration enables streamlined tracking and resolution without switching between platforms.
## Get reports
> This option gives you the ability to generate finding specific detailed reports in either a JSON, PDF, or CSV format. these reports will contain all pertinent finding details including All relevant finding information (names, descriptions, and Reachability analysis), References (CVE, EPSS, CVSS, advisories) , and detailed component vulnerability information (Offset or relative address, handler information, pseudo code representation).
**Generating Detailed Reports**
The "Get Reports" feature enables users to generate comprehensive, finding-specific reports in JSON or PDF formats. These reports provide a thorough breakdown of all pertinent details related to identified findings, ensuring complete visibility into vulnerabilities and associated risks. Key elements included in the reports are:
1. Finding Information:
* Names and descriptions of the findings.
* Reachability analysis, highlighting how vulnerabilities can be accessed and exploited.
2. References:
* Detailed citations such as CVE (Common Vulnerabilities and Exposures) IDs, EPSS (Exploit Prediction Scoring System) data, and CVSS (Common Vulnerability Scoring System) metrics.
* Links to relevant advisories for remediation guidance.
3. Component Vulnerability Insights:
* Precise information on vulnerabilities within specific components, including offsets, relative addresses, and handler details.
* Pseudocode representations that illustrate the functionality and potential exploitation paths within the analyzed binaries.
## Findings types
### Unknown Vulnerabilities
These are zero-day vulnerabilities requiring immediate attention. Unknown Vulnerability Analysis identifies vulnerabilities within specific classes, such as NVRAM variable handling and SMM callouts. The component section details the affected module's name, hash, GUID Path, AData size vulnerability, and Architecture. Depending on the finding type, additional data may include callout and handler offsets, variable names, locations, and other relevant details. Descriptions are based on triggered rules but are unique to the customer's environment. Data from Unknown Vulnerability Analysis should be tightly controlled until the finding's exploitability has been validated or the vulnerability has been mitigated or remediated.
#### Vulnerability Detail
![]()
*Vulnerability location detail*
![]()
![]()
*Psudocode representation*
### Known Vulnerabilities
Refer to security flaws in software, firmware, or components that have been identified, documented, and assigned identifiers like Common Vulnerabilities and Exposures (CVEs) and, Exploit Predictability (EPSS) . These vulnerabilities are publicized to inform organizations, developers, and security teams to implement appropriate mitigations or patches. Known Vulnerability findings Include extensive detail to help analysts and security Engineers better understand the known vulnerabilities and prioritize mitigation. details provided include the aforementioned industry references, reachability analysis, In-depth component vulnerability detail as well as pseudocode representations of the vulnerability. Here’s an overview of key aspects of known vulnerabilities:
![]()
### Malicious Code Detection
This involves identifying harmful entities such as malicious implants, hooks, embedded executables, or other anomalies within analyzed images, offering robust security analysis and risk mitigation to businesses. These elements are crafted by attackers to infiltrate, persist, and potentially exfiltrate sensitive data or compromise a system.
Malicious code can evade current defense platforms because it blends in with standard functionality and can remain dormant or operate in stealth for long periods of time. The Binarly Transparency Platform identifies the module name and type, then checks for the existence of embedded executables, Malicious Hooks, and their functions, as well as Firmware Implants. Findings provide in-depth details as to the severity, location, and capabilities associated with the detected threat(s) including module type, name, kind or function, Offset (virtual address), and industry references.
![]()
### Dependency Findings
Dependency findings focus on identifying vulnerabilities within both direct and transitive software dependencies. These vulnerabilities may arise in open-source libraries or other third-party components utilized in software development, potentially introducing supply chain risks. Dependency vulnerabilities constitute a significant portion of third-party supply chain issues, making it essential to identify vulnerable or potentially at-risk components and subcomponents embedded in software. This is critical for understanding risks that may not be immediately apparent at the application level.
Dependency findings include standard industry references such as CVE (Common Vulnerabilities and Exposures), CWE (Common Weakness Enumerations), and CVSS (Common Vulnerability Scoring System). These references are derived from queries to the National Vulnerability Database (NVD) based on key characteristics of the identified components and dependencies.
In addition to these references, further analysis enhances the findings with identifiers such as GitHub security advisories, EPSS (Exploit Prediction Scoring System), and CISA references, including Known Exploited Vulnerabilities (KEV) and known ransomware associations. Custom reachability analysis and fix information is also provided for deeper insights and critical prioritization information.
Vulnerable component details include attributes such as name, GUID, path, magic strings, and architecture, offering comprehensive context for prioritizing and addressing risks effectively.
*Dependency references* ![]()
### Cryptographic Findings
The Cryptographic Materials tab isolates all detected algorithms, protocols, certificates, and keys discovered in the image. Findings include compliance assessments (weak, deprecated, quantum-vulnerable), certificate parameters, key material details, confidence scores, and reachability analysis. Reports can be generated directly from this tab as a PQC Compliance Report or CBOM export.
For a full walkthrough of the tab, see [Cryptographic Materials](/user-guides/image-scans/cryptographic-materials).
![Crypto1 Pn]()
![Crypto2 Pn]()
### Secure By Design
\
These findings call out risks and issues that can impact the integrity and security of software and hardware supply chains. They typically surface during manufacturing, distribution, or integration and point to deviations from CISA’s Secure by Design guidance and the NIST SP 800-218 secure development framework. Issues are categorized as unsafe functions, mitigation failures, weaknesses, expired certificates, and known exploited vulnerabilities (KEVs).
Mitigation & Weaknesses identify misconfigurations or flaws in firmware or software, which could potentially lead to security breaches. The vast majority of these findings are low in severity, as they typically reflect an oversight or failure to implement practices in software development that could enhance or harden the security of the affected components, rather than a vulnerability or threat being present.
Examples include usage of unsafe functions and failure to implement protection mechanisms such as RELRO, Stack Canaries, and Control Flow.
Finding details for mitigations and weaknesses include classifications that outline Common Weakness Enumerations (CWE), details about impacted components, and specific information about the finding. This may include impacted function lists, associated references, and other relevant contextual data. In this screenshot, we are investigating Missing Stack Canaries.
![]()
Full list of hardening checks by platform — Linux/POSIX and UEFI firmware — including analysis depth, per-function coverage, and comparison with checksec.
### Secret Findings
The platform utilizes regex-based rules to detect hardcoded sensitive information, such as API keys, JSON web tokens, OAuth tokens, encryption keys, or webhook URLs embedded within scripts or files. If exposed, such secrets could be exploited by attackers. While secrets can be identified in any image analyzed by the platform, they are particularly prevalent in Docker containers and embedded Linux firmware.
Finding details for secrets include classifications aligned with Common Weakness Enumerations (CWE) and detailed descriptions of the identified issue. Component details specify the location or the specific component, script, or file in which the embedded secret was discovered. Evidence information includes the actual secret value and its entropy, providing a thorough context for addressing the risk.
For details on detection scope, input coverage, and secret validation, see [Secrets Detection](/resource-center/secrets-detection).
![]()
![]()
### Components Tab
The Component tab displays a static tree view of the various components identified within the analyzed binary. While this tab does not provide extensive details about the individual components, it offers valuable insights into the overall structure and hierarchy of the discovered components.
The root of the analyzed file is represented as input.bin, corresponding to the top-level file uploaded to the platform for analysis. This provides users with a clear representation of the parent file and its associated components.
For more detailed information on the identified components and to access export capabilities, it is recommended to generate a Software Bill of Materials (SBOM). Detailed instructions on SBOM generation and usage are covered in the Platform Outputs section of this guide.
The tab is split into two views. **All** holds the component tree described above, with a search box for locating a component by name. **Reduced analysis coverage** lists the components that were left out of code analysis because their code size exceeded the configured limit, with the number of such components shown next to the view name. When every component was analysed in full, the view is empty and cannot be selected.
![Components tab showing the All component tree and a Reduced analysis coverage view holding three components.]()
Each row in Reduced analysis coverage names the component, its code size, the path it was found at, and the reason it was skipped. Type in the Component or Path filter to narrow the list by substring, and sort on Code size to see the largest components first. The Reason column shows the limit the component was measured against, so a component listed at 55.83 MB against a 38.15 MB limit tells you both numbers at a glance.
![Reduced analysis coverage grid with three vmlinux.elf components of 55.83 MB code size, each exceeding a 38.15 MB code size limit.]()
A skipped component is still inventoried and still appears in the tree under All. Only the analysis of its code was left out, so it contributes no findings. See [Code Size Limit](/resource-center/code-size-limit) for how code size is measured and what to do when you need a skipped component analysed.
### History Tab
The History tab provides comprehensive historical tracking of actions taken on a selected product and its analyzed images. It records scan actions, offering visibility into all activities performed for a specific product. This view is particularly useful for tracking the user who initiated a scan, the dates and times when scans were started and completed, and the duration of each scan.
Although the History tab focuses on tracking actions specific to the selected image within a product, a broader scan history view for all scans performed across the platform is available. This platform-wide history can be accessed via the Scans menu in the vertical navigation options on the left side of the interface. This feature enables users to monitor scan activities efficiently at both the individual product level and the platform-wide level.
# Compare Images
Source: https://docs.binarly.io/user-guides/image-scans/compare
The Compare Images feature enables comparison of the findings from two images within the same product, showing which findings are present in which image. This can be used to verify that specific vulnerabilities or security issues have been successfully addressed between image versions. It's also useful when trying to identify security regressions or new vulnerabilities that may have been introduced.
Images can be compared from the product dashboard by selecting the two images you want to compare from the list using the checkboxes left of the image's title (see below).
![A list of two images on the product page]()
Once exactly two images are selected, the compare option will show up (see below). Clicking it will open the compare view for the selected images.
![A list of two selected images on the product page with the comparison button visible above the image list.]()
The compare view can also be reached from the top compare button (see below). This one is always visible and will open the compare view with the two most recent images selected.
![The alternative comparison button on the top of the product dashboard.]()
On the compare view, the names of the images that are being compared are shown on top and can be changed by selecting different images from the dropdowns (see below).
![Left image name dropdown opened.]()
However the comparison view is opened, it always lists all findings that are in at least one of the two images being compared. The list behaves just like the [findings grid](/user-guides/image-scans/all-about-details#finding-details) and supports custom views and different columns, filters and sort orders. One difference is that it has an additional column called Comparison that shows for every finding whether it's
* Not Found: present in the left image but not the right,
* Found: present in the right image but not the left, or
* Not Changed: present in both images.
## Comparing Images
To verify a finding was remediated and thus no longer exists in an image, first select the vulnerable image, the one where the finding is present, on the right and the fixed image on the left of the comparison view. If they're on opposite sides of the comparison view, the swap button between them (marked below) swaps the images around.
![Image of the swap button between the two image name dropdowns.]()
Once the order is correct, filter the Comparison column for the Not Found entries only to exclude the findings that are present in both images. The result is the list of remediated findings (see below).
![The findings list on the image comparison view with only Not Found findings.]()
Reversing the order of the two images using the swap button and filtering by the Comparison column's Found entries will show the opposite situation: all newly detected vulnerabilities (see below).
![The findings list on the image comparison view with only Found findings.]()
## Programmatic Access
Compare images programmatically using the Binarly API:
* [Triage & Analysis API](/api-reference/use-cases/triage-and-analysis) - Compare images via API
# Cryptographic Materials
Source: https://docs.binarly.io/user-guides/image-scans/cryptographic-materials
Using the Cryptographic Materials tab to review algorithms, certificates, and keys discovered in an image scan.
The Cryptographic Materials tab provides an isolated view of all cryptographic findings discovered during a scan. Navigate to an image scan detail view and select **Cryptographic Materials** from the tabbed navigation to access it.
The tab surfaces detected algorithms, protocols, certificates, and keys across all components in the analyzed image, enabling compliance assessment, post-quantum migration planning, and risk prioritization.
## Grid Columns
The grid presents one row per cryptographic finding. All columns support sorting, filtering, and reordering.
| Column | Description |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Type** | Category of the finding: Algorithm, Protocol, Certificate, or Key |
| **Finding / Class** | Finding class identifier (e.g., `crypto/algorithm/hashing/md5`, `crypto/certificate/expired`) |
| **Component** | Binary component in which the material was found |
| **Severity** | Risk level assigned to the finding |
| **Confidence** | How certain BTP is that it identified the correct algorithm and its exact parameters — uses the same five-level scale as all other findings (see [Accuracy & Confidence](/resource-center/accuracy-confidence)) |
| **Reachability** | Whether the cryptographic material is accessible from a public entry point in the binary (see [Reachability Analysis](/resource-center/asap)); applies to algorithms and protocols |
| **PQC Status** | Post-quantum compliance classification per NIST IR 8547: compliant, non-compliant, or acceptable until a specified date |
## Algorithm Findings
Algorithm findings identify cryptographic algorithm implementations in the analyzed binary. Each finding includes:
* Algorithm class and detected parameters (key size, mode of operation)
* Component name and offset where the implementation was found
* Function addresses associated with the cryptographic code
* Reachability result
* PQC compliance status
## Certificate Findings
Certificate findings expose X.509 certificates embedded in the image. The finding detail view provides:
* **Issuer** and **Subject** - certificate authority and the entity the certificate was issued to
* **Origin** - component path within the image where the certificate was found
* **Validity period** - not-before and not-after dates
* **Expiration status** - whether the certificate has expired
* **Signature algorithm** - algorithm used to sign the certificate
* **Public key algorithm and size** - e.g., RSA-2048, EC P-256
* **Self-signed flag** - whether the certificate is self-signed
Certificate issue classes (`crypto/certificate/expired`, `crypto/certificate/invalid`, `crypto/certificate/self-signed`, `crypto/certificate/untrusted`) carry severity ratings. Certificates without issues are recorded as `artefact/crypto-certificate-material` and are informative.
## Key Findings
Key material findings record cryptographic keys embedded in the binary:
* **Key type** - RSA, EC, Ed25519, post-quantum, or other
* **Key size / parameters** - bit-length or parameter set
* **Location** - component path and offset within the image
* **Classification** - private key vs. public key
Private keys found in firmware are additionally flagged under `secret/private-key` or `secret/encryption-key`, which carry elevated severity due to the risk of key exposure.
## Filtering and Searching
**Quick column filters:**
* Filter by **Type** to narrow to Algorithms, Protocols, Certificates, or Keys.
* Filter by **Finding / Class** by class prefix - e.g., `crypto/algorithm/hashing` for hashing algorithms, `crypto/certificate` for certificate findings.
* Filter by **PQC Status** to isolate quantum-vulnerable findings for migration planning.
* Filter by **Severity** to surface only weak or deprecated materials.
**Advanced filtering:**
Open the Filters drawer (upper-right of the grid) to build multi-criteria filters across severity, confidence, reachability, component, and other fields. See [CVSS Vector Filtering](/user-guides/image-scans/cvss-vector-filtering).
Save a filter combining `PQC Status: non-compliant` and `Reachability: reachable` as a named Saved View. This surfaces quantum-vulnerable algorithm usages that are actively reachable - the highest-priority set for migration planning. See [Saved Views](/user-guides/important-findings/saved-views).
## Generating Reports
Click the **Generate** button in the tab to produce a PDF or JSON report listing all quantum-vulnerable algorithm instances with NIST IR 8547 migration guidance.
See [PQC Compliance Report](/user-guides/export/pqc) for report contents and format details.
Open the action menu and select **Download CBOM** to export a CycloneDX-formatted inventory of all detected cryptographic materials.
See [CBOM Export](/user-guides/export/cbom) for format details and programmatic access.
## Related
* [Cryptographic Detection](/resource-center/cryptographic-detection) - How detection works
* [Algorithm Compliance Reference](/resource-center/algorithm-compliance) - Compliance status for all algorithm classes
* [Finding Classes Reference](/resource-center/finding-classes) - Full list of `crypto/*` classes
* [Accuracy & Confidence in Findings](/resource-center/accuracy-confidence)
* [Reachability Analysis](/resource-center/asap)
* [PQC Compliance Report](/user-guides/export/pqc)
* [CBOM Export](/user-guides/export/cbom)
# CVSS Vector Filtering
Source: https://docs.binarly.io/user-guides/image-scans/cvss-vector-filtering
Filter the Findings Grid by CVSS v3 vector elements to focus on specific attack characteristics and prioritize remediation.
## Overview
The Findings Grid supports filtering by all CVSS v3 vector elements, allowing you to focus on findings with specific attack characteristics. This helps prioritize vulnerabilities based on how they can be exploited.
![Findings grid showing CVSS columns]()
## Available CVSS Vector Filters
Access all CVSS filters from the **Sorting & Filters, Columns Settings** panel by clicking the filter icon in the grid header.
![Filter panel with CVSS vector options]()
### Vector Elements
| Filter | Values | Description |
| ------------------------------------ | ---------------------------------- | ---------------------------------------------------------------------------- |
| **CVSS** *(legacy)* | Range 0.0 - 10.0 | Overall CVSS score. Hidden by default, can be re-enabled in column settings. |
| **CVSS v3** | Range 0.0 - 10.0 | CVSS v3 base score |
| **Attack Vector (CVSS v3)** | Network, Adjacent, Local, Physical | How the vulnerability can be exploited |
| **Attack Complexity (CVSS v3)** | Low, High | Conditions beyond attacker control that must exist |
| **Privileges Required (CVSS v3)** | None, Low, High | Level of privileges an attacker must possess |
| **User Interaction (CVSS v3)** | None, Required | Whether a user must participate |
| **Scope (CVSS v3)** | Unchanged, Changed | Whether impact extends beyond the vulnerable component |
| **Confidentiality Impact (CVSS v3)** | None, Low, High | Impact on information confidentiality |
| **Integrity Impact (CVSS v3)** | None, Low, High | Impact on information integrity |
| **Availability Impact (CVSS v3)** | None, Low, High | Impact on system availability |
## Using CVSS Filters
1. Click the **filter/settings icon** in the Findings grid header
2. Expand the **Sorting & Filters, Columns Settings** panel
3. Select values for one or more CVSS vector elements
4. Click **Apply** to filter the results
### Example: High-Risk Network Vulnerabilities
To find critical network-exploitable vulnerabilities:
1. Set **Attack Vector (CVSS v3)** to `Network (AV:N)`
2. Set **Privileges Required (CVSS v3)** to `None (PR:N)`
3. Click **Apply**
The results show only findings matching your criteria:
![Filtered results with CVSS columns]()
## Column Display
Customize which CVSS columns appear in the grid via the **Display columns** panel.
![Column settings panel]()
The grid displays CVSS values in a compact format:
| Column | Display Format | Example |
| ---------------------- | -------------- | ---------------------------------- |
| Attack Vector | `Value (AV:X)` | `Network (AV:N)`, `Local (AV:L)` |
| Attack Complexity | `Value (AC:X)` | `Low (AC:L)`, `High (AC:H)` |
| Privileges Required | `Value (PR:X)` | `None (PR:N)`, `High (PR:H)` |
| User Interaction | `Value (UI:X)` | `None (UI:N)`, `Required (UI:R)` |
| Scope | `Value (S:X)` | `Unchanged (S:U)`, `Changed (S:C)` |
| Confidentiality Impact | `Value (C:X)` | `None (C:N)`, `High (C:H)` |
| Integrity Impact | `Value (I:X)` | `None (I:N)`, `High (I:H)` |
| Availability Impact | `Value (A:X)` | `None (A:N)`, `High (A:H)` |
## Integration with Saved Views
CVSS vector filters integrate seamlessly with [Saved Views](/user-guides/important-findings/saved-views):
* Save filter configurations for quick access
* Include CVSS columns in your default view
* Share filtered views across the organization
Use the **View Saved Filters** dropdown to save or load filter presets.
## Related
* [Findings Scope](/user-guides/image-scans/findings-scope) - Control which finding types appear in the grid per product
* [Saved Views](/user-guides/important-findings/saved-views) - Save and share filter configurations
* [Finding Types & Classes](/resource-center/finding-types) - Reference for all finding types and classes
# Finding Variants
Source: https://docs.binarly.io/user-guides/image-scans/finding-variants
Finding Variants provides an ability to use vulnerability information from alternative sources for finding prioritization.
## Overview
By default, finding attributes — severity, CVSS scores, references, and classifications, etc. — are compiled by Binarly from several sources. For known vulnerabilities, additional data from external advisory sources is also available as **Variants**. For a full list of supported sources, see [Vulnerability Data Sources](/resource-center/vdb-sources).
Finding Variants lets you configure a prioritized list of alternative sources per product. When a finding has a variant from one of those sources, this variant gets applied, which means that its attributes override the corresponding attributes of the finding. This affects the findings grid, sorting, filtering, dashboard charts, and exports.
A common use case is applying ecosystem-reported severities that differ from the original finding severity. For example, the OpenSSL project rates CVE-2024-5535 as **Low**, while the NVD severity might be **Critical**. Configuring `openssl` as a source will surface the ecosystem's own assessment for all affected findings in the product.
## How It Works
When a source list is configured for a product:
* Each finding is checked for a variant from the **first matching source** in the priority list.
* If a matching variant exists, its available attributes override the corresponding finding attributes. Attributes not present in the variant remain unchanged.
* If the source list is changed or a source is removed, affected findings are recalculated automatically — either falling back to a lower-priority source or reverting to the original finding attributes.
## Configuring Finding Variants
Finding Variants is configured from the Products page.
1. Navigate to the three-dot menu in the **Actions** column on the chosen Product's row
2. Click **Finding Variants**
![Products grid showing Finding Variants action in menu]()
### Adding and Ordering Sources
1. In the **Finding Variants** drawer, add sources from the predefined list
2. Drag sources to set their priority order — sources higher in the list take precedence
3. Click **Apply**
![Finding Variants drawer with source list]()
> **Note:** At most one variant is applied per finding — from the first source in the priority list for which a matching variant exists. If no configured source matches any of a finding's available variants, the original finding attributes are used.
### Sync Status
After applying changes, all findings in the product are recalculated asynchronously. The product's row in the Products grid will show a sync indicator:
* **Updating...** - Variant application policy is being applied.
![Status showing Updating]()
* **Synced** - Variants are fully applied.
![Status showing Synced]()
## Viewing Variants on Finding Details
The **Variants** tab on the Finding Details page shows all available variants for a finding, including their individual fields and source attribution.
![Finding Details page showing Variants tab]()
The currently applied variant is marked as **applied**. If no source is configured or no matching variant exists, the original finding attributes are used and no applied marker is shown.
![Variants tab showing Applied variant highlighted]()
> **Note:** Variants listed under `{source}/{identifier}` keys are shown on this tab for reference but are not eligible for override configuration.
## Related
* [Vulnerability Data Sources](/resource-center/vdb-sources) — Reference for all supported vulnerability data sources
# Findings Scope
Source: https://docs.binarly.io/user-guides/image-scans/findings-scope
Findings Scope limits reported findings for a product by disabling certain finding types not relevant to the product threat model. This helps with noise reduction and fine-tuning of reports and dashboard content.
## Overview
Findings Scope allows you to customize which finding types are visible for each product. Disabled finding types are hidden from:
* Dashboard charts and statistics
* Findings grid counts
* Exports and reports
For a complete reference of finding types and their associated classes, see [Finding Types & Classes](/resource-center/finding-types).
## Configuring Findings Scope
Findings Scope can be configured from the Products page or from an individual Product page.
### From Products Page
1. Navigate to the three-dot menu in the **Actions** column on the chosen Product's row
2. Click **Findings Scope**
![Products grid showing Findings Scope action in menu]()
### From Product Page
Click the **Findings Scope** button in the product header.
![Product page showing Findings Scope button]()
### Configuring Finding Types
1. In the Findings Scope drawer, unselect the Finding Types you want to hide
2. Click **Apply**
![Findings Scope drawer with finding type toggles]()
The drawer organizes finding types into categories:
* **Cryptographic materials, algorithms and protocols** - Crypto assets, certificates, keys
* **Secrets and credentials** - Embedded credentials
* **Weak binaries and configuration** - Missing mitigations, weaknesses
* **Vulnerable code patterns** - Zero-day vulnerabilities
* **Known vulnerabilities** - CVEs, supply chain issues, dependency vulnerabilities
* **Suspicious code** - Potential tampering or obfuscation
* **Malicious code** - Confirmed malicious behavior and known threats
### Sync Status
After applying changes, wait for the scope to sync:
* **Updating...** - Scope is being applied. Wait and refresh the page.
![Status showing Updating]()
* **Synced** - Scope is fully applied.
![Status showing Synced]()
## Browsing Ignored Findings
You can view findings hidden by scope using the **Scope/Ignored** toggle in the findings grid header.
### View Ignored Findings
Click **Ignored** to see findings excluded by scope settings:
![Findings grid showing Ignored view]()
### Return to Scoped View
Click **Scope** to return to the filtered view:
![Findings grid showing Scope view]()
> **Note:** Toggling between Scope and Ignored views preserves your other filter and sort settings.
## Related
* [CVSS Vector Filtering](/user-guides/image-scans/cvss-vector-filtering) - Filter the findings grid by individual CVSS v3 vector elements
* [Finding Types & Classes](/resource-center/finding-types) - Complete reference for all finding types and their associated classes
# Products
Source: https://docs.binarly.io/user-guides/image-scans/products
## What are Products?
Products serve as containers designed to represent development, security review, analysis, research, or assessment efforts. This provides a logical grouping mechanism for images and container files analyzed by the platform. For example, a product line or device model would be ideal in a development life cycle scenario, e.g., Acme Power Server 1000. In an embedded Linux or container scenario, a specific version of an OS or set of components analyzed would ideally be a product, e.g., Mint22-Wilma
### Benefits of Using Products
* Streamlined Organization: Ensures that related images and findings are logically grouped for easier navigation and analysis.
* Improved Analysis and Reporting: Allows for focused vulnerability and security assessments tied to specific product lines, device models, or software versions.
* Scalable Management: Simplifies tracking and management of complex data sets across diverse projects or product categories.
## Managing Products
Effective product management within the Binarly Transparency Platform relies on a logical and consistent naming convention. This ensures clarity and organization when creating and associating images with products.
### Creating New Products
New products can be created using the action menus located in the:
1. Upper Right Corner:
* Provides an option to create a new product.
* Best for adding products without immediately associating an image.
2. Lower Left Corner:
* Offers the same product creation option.
* Additionally, prompts you to upload an image for analysis during the creation process as well as setting a version.
### Naming Products
Product names are free-form fields, allowing flexibility in naming conventions. It is recommended to use logical and descriptive names that clearly identify the purpose or content of the product.
### Examples of Product Names:
* Device-Specific Names:
* Acme Business Server 1500
* Router Firmware for Model Z100
* File or Container Types:
* Web Services Docker
* Linux Kernel Firmware
* Use Case Descriptions:
* Cloud Storage for Edge Device Updates
* IoT Firmware Updates for Manufacturing
### Best Practices for Managing Products
1. Establish a logical and consistent vocabulary for product names to enhance organization and searchability.
2. Associate related images with their respective products to streamline analysis and reporting.
3. Regularly review and update product names to reflect changes in development, analysis, or assessment efforts.
## Creating a Product
The Binarly Transparency Platform provides flexible options for creating new products, allowing users to organize and manage images effectively. Products can be created directly or as part of the image upload process.
### Steps to Create a Product
1. Using the Action Menus:
* Navigate to one of the action menus located in the:
* Upper Right Corner: Ideal for creating a product without uploading an image.
* Lower Left Corner: Offers the same product creation functionality but integrates image upload options.
* Enter the desired Product Name in the free-form field.
* Click Create to finalize the product.
2. Using the "Upload Image" Option:
* Click the "Upload Image" button located in the lower left corner of the interface.
* The Image Upload Dialog will appear, providing two options:
* Select an existing product name to associate the uploaded image.
* Create a new product name:
* When prompted, select "Create (New Product Name)".
* Enter the desired product name in the provided field.
* Complete the process by uploading the image.
### Best Practices for Product Creation
* Choose logical and descriptive names that clearly identify the product’s purpose or associated images.
* Ensure product names align with your organization’s naming conventions for easier searchability and management.
* Use the "Upload Image" workflow when directly associating an image with a newly created product.
> ![]()
Products can be set up as placeholders without requiring immediate image uploads. Alternatively, you can create products dynamically when uploading specific images. There is no limit to the number of products that can be made. Products should be used as logical organizational units for related or similar images that require analysis. Product licensing may be tied to the number of products in specific scenarios, such as OEMs or firmware manufacturers. If you need clarification on your product licensing, please contact support at [support@binarly.io](mailto:support@binarly.io) or your account representative.
## Archiving a Product
The Binarly Transparency Platform allows users to archive products to streamline the active grid view without permanently deleting data. Archiving helps manage the workspace by moving less relevant or inactive products out of the primary view.
### Archiving a Product
To archive a product:
1. Navigate to the three-dot menu located on the far right of the product’s row in the active grid view.
2. Select "Archive Product" from the dropdown menu.
* Archiving moves the product and its associated images to the archived view.
3. Additional options in the three-dot menu:
* Rename the product for better organization.
* Upload additional images to the product if needed before archiving.
![]()
### Accessing Archived Products
1. Switch to the archived grid view:
* In the action menu at the upper right corner, select the archived filter grid option.
2. The archived grid view displays:
* Archived products and their associated details.
* Information such as who created and archived the product.
### Unarchiving a Product
If you need to restore an archived product:
1. In the archived grid view, locate the product you wish to restore.
2. Navigate to the three-dot menu on the far right of the grid.
3. Select "Unarchive Product" to move the product and its data back to the active grid view.
Archiving and unarchiving products ensures that the workspace remains organized, providing flexibility to manage both active and inactive projects effectively.
> ![]()
# Filtering findings by reachability
Source: https://docs.binarly.io/user-guides/image-scans/reachability-filtering
Read the Code Reachability and Environment Reachability columns together to scope the Findings grid to vulnerabilities whose code both loads in the deployment and is reachable inside its binary.
The Findings grid reports reachability in two columns: Code Reachability and Environment Reachability. Code Reachability answers whether the vulnerable code is reachable inside its own binary, Binarly's intra-component reachability analysis. Environment Reachability answers whether that component runs or loads in the assumed runtime environment, the layer [Attack Surface Approximation and Prioritisation (ASAP)](/resource-center/asap) adds on top. Read together, they're the strongest static signal Binarly can give for whether a finding sits on the attack surface, and each column has its own filter.
![The Code Reachability and Environment Reachability columns in the Findings grid.]()
## Prerequisites
* A completed image scan with findings.
* Access to the Findings grid for the image or product.
## The two reachability columns
Each column answers a different question. Environment Reachability asks whether the component runs at all in the package. Code Reachability asks whether, once it runs, execution can reach the vulnerable code. Neither answer alone confirms that the vulnerable code runs; together, they're the clearest static evidence available.
### Code Reachability
Whether the vulnerable code is reachable from an entry-point inside the component that contains it.
| Value | Meaning |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Entrypoint** | A path exists from the component's original entry-point, such as `main` or `start`, to the vulnerable location. Strongest in-binary signal. |
| **Exported** | Reachable from a viable exported entry-point. For shared libraries this is an exported function. For UEFI it covers identified SMI handlers and functions in registered protocol interfaces and PPIs. |
| **Referenced** | Referenced by reachable code, but a static path could not be confirmed. |
| **Undetermined** | There is analysable code, but its reachability could not be determined statically. |
| **N/A** | There is no analysable code for the finding, so code reachability does not apply. |
![The Code Reachability column filter.]()
### Environment Reachability
Whether the component runs or loads in the package's assumed runtime environment.
| Value | Meaning |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Entrypoint** | Reachable from the environment's advertised entry-point, such as a container's entrypoint. The component runs. |
| **Runtime Invocation** | Another running component may invoke it at runtime. The component likely runs. |
| **Runtime Dependency** | Another component loads it as a dependency, for example through dynamic linking. The component is loaded, but the code may not be invoked. |
| **Undetermined** | Reachability could not be determined, or the component is outside the assumed attack surface. |
![The Environment Reachability column filter.]()
## How reachability differs by ecosystem
The same column value is derived differently depending on the package. Code Reachability depends on what counts as an entry-point inside a binary, and Environment Reachability depends on how the package declares what runs. The Ecosystem column is the kind of package you uploaded; the Environment class is the label ASAP assigns once it identifies that package. Use this table to read the columns in the right context. See [Reachability analysis (ASAP)](/resource-center/asap) for the full model.
| Ecosystem | Environment class | How the platform decides what runs | Code entry-points inside a component |
| ----------------------------------------- | ------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Container | Container | OCI image config: `Entrypoint`, `Cmd`, and `Env` | ELF executables (`main` or `start`) and shared-library exports |
| Linux (system image, Linux-like firmware) | System image, or Undetermined for BMC-like images | Start-up scripts, such as those under `/etc/init.d/` | ELF executables (`main` or `start`) and shared-library exports |
| UEFI (system firmware) | System firmware | Modules present in the firmware image structure | Module protocol interfaces, PPIs, registered event handlers, and identified SMI handlers; ISRs for firmware with an Interrupt Vector Table |
Reading this in practice, take each column in turn:
* **Code Reachability** reads the same on containers and Linux images, because both hold ELF binaries: `main` or `start` gives Entrypoint, and shared-library exports give Exported. UEFI has no `main`-style entry, so its reachable code is almost always Exported, entered through protocol interfaces, PPIs, registered event handlers, and SMI handlers.
* **Environment Reachability** starts from how each package declares what runs: containers from the OCI config, Linux images from start-up scripts, UEFI from the modules in the firmware image. Across all three, a component that runs shows Entrypoint, one component invoking another shows Runtime Invocation, and a loaded but possibly unused dependency shows Runtime Dependency. Runtime Dependency comes from dynamic linking, so it appears on containers and Linux, and rarely on UEFI, where modules interact through protocols and PPIs and show Runtime Invocation instead.
On UEFI findings, Exported is the strong Code Reachability signal, not a weaker one. Do not deprioritise a UEFI finding only because it is not marked Entrypoint. A module's reachable code is entered through its protocol interfaces, PPIs, event handlers, and SMI handlers, which the platform classifies as Exported.
## Reading the two columns together
Environment Reachability places the component on the attack surface. Code Reachability confirms the vulnerable path inside it. A finding is most likely to be executed when both signals are strong. This pairing holds for every ecosystem, but which values you actually see depends on it: on UEFI, the strong Code Reachability signal is Exported rather than Entrypoint, as covered in [How reachability differs by ecosystem](#how-reachability-differs-by-ecosystem). Read the pair against this table:
| Environment Reachability | Code Reachability | What it means |
| -------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Entrypoint or Runtime Invocation | Entrypoint or Exported | The component runs and the vulnerable code is reachable inside it. On the attack surface, highest priority. |
| Entrypoint or Runtime Invocation | Referenced, Undetermined, or N/A | The component runs, but the vulnerable path inside it is not confirmed. Weigh with severity and exploitability. |
| Runtime Dependency | Any | The component is loaded as a dependency but may never be invoked. Check whether the depending component calls the vulnerable function before acting. |
| Undetermined | Any | The component was not placed on the assumed attack surface. Deprioritise, and revisit if your deployment differs from the assumed environment. |
Undetermined means there is code but its reachability could not be confirmed statically. N/A means there is no analysable code for the finding. Neither proves the code never runs, so keep both for a second pass rather than discarding them.
## Filter the grid by reachability
Each column has its own filter in the grid header.
Click the funnel icon in the Code Reachability or Environment Reachability column header.
Tick the values you want to see. Use Search in filters to find a value, or Select All to start from everything. A finding matches when its value is in your selection.
Click OK to apply, or Clear to reset the column. The grid updates and writes the filter state to the page URL, so you can bookmark or share it.
Filter Environment Reachability and Code Reachability together to scope to findings that both run and are reachable in-binary.
## Example: reachable, open known vulnerabilities
Build a triage view for known vulnerabilities that are most likely executed and still open:
* **Type** is Known Vulnerability.
* **Environment Reachability** is Entrypoint or Runtime Invocation.
* **Code Reachability** is Entrypoint or Exported.
* **Status** is New or In Progress, with **Ignored** off.
Sort by Risk Score, highest first. Reachability already feeds risk scoring, so reachable findings sort toward the top. To widen the net for a second pass, add Runtime Dependency and Referenced, then work down from there.
This answers the ASAP question directly: of the known vulnerabilities present, which sit on code that runs and is reachable inside its binary. It is a strong default for a triage queue.
## On the finding detail
Open a finding to see both signals in full.
* Code Reachability shows the Status and links to the reachability trace evidence.
* Environment Reachability shows the Environment it was derived from, the Reachability kind, and the components the reachability comes from under **from Component(s)**, each with its path.
When a component is reachable from more than one other component, the Environment Reachability cell shows a count, such as `2 ER`, and the detail lists each source under **from Component(s)**. Check each component listed there to see whether it calls the vulnerable function.
![Code Reachability status on a finding.]()
![Environment Reachability on a finding, with the components it is reachable from.]()
Each property changes how much weight the reachability carries:
| Property | Column | Impact on the execution judgement |
| --------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status** | Code Reachability | The in-binary class. Entrypoint and Exported put the vulnerable code on a reachable path; Referenced and Undetermined do not confirm it. |
| **Environment** | Environment Reachability | The environment class ASAP detected: Container, System image, System firmware, or Undetermined. A precise class means the runtime seeds are well defined. Undetermined means the environment could not be pinned down, for example a BMC image that resembles a generic Linux image, so treat its reachability as weaker evidence. |
| **Reachability** | Environment Reachability | The reachability kind that decides whether the component runs or is only loaded. |
| **from Component(s)** | Environment Reachability | The referent components that invoke or depend on this one, each with its path. |
## Save and share the view
Once the filters and sorting are set, keep the view for reuse:
* Save the filter, sort, and column settings as a [Saved View](/user-guides/important-findings/saved-views). Saved Views are scoped to the grid category (Global, Product Image, and so on).
* Copy the page URL to hand a teammate the same view. The grid encodes filters, sorting, and page state in the URL.
## Related
How Binarly computes the Code and Environment Reachability behind these filters.
Save and reuse filtered, sorted grid views.
Where reachability appears on an individual finding.
Filter findings by CVSS vector components.
# Prioritizing with the Risk Score
Source: https://docs.binarly.io/user-guides/image-scans/risk-score
Use the Binarly Risk Score to rank findings by priority: pick a scoring profile, read the score, and sort and filter findings by risk score.
The Binarly Risk Score gives every finding a single priority number between 0 and 1, so you can work the list from most to least urgent instead of juggling CVSS, EPSS, KEV, and reachability by hand. This guide covers choosing a profile, reading the score, and using it to triage findings. For the algorithm and the full metric set, see [Binarly Risk Score](/resource-center/binarly-risk-score) in the Resource Center.
## Why one score
Different scoring systems disagree about what matters. A vulnerability that CVSS ranks near the bottom can be the one with an active public exploit; a high CVSS can sit in code that never runs. The heatmap below ranks the same six vulnerabilities under CVSS, EPSS, and the three Binarly Risk Score profiles: the order changes with each system.
![Heatmap of six vulnerabilities ranked across CVSS, EPSS, and the Balanced, Decision Impact (Actionable Risk), and Exploitation (Exploitability) Binarly Risk Score profiles.]()
The Binarly Risk Score folds exploitation, impact, decision, and finding-type signals into one number, so a finding rises to the top when several signals agree, not because one metric happens to be high.
## Choose a profile
A profile decides how much weight each group of signals carries. The platform ships three, and Decision Impact (Actionable Risk) is the default. Pick the one that matches what you are doing:
| Profile | Emphasises | Use it when |
| ------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Balanced** | All four signal groups equally | You want a general-purpose ranking or a baseline review. |
| **Exploitation (Exploitability)** | The exploitation signals (EPSS, EMS, KEV, public exploits) | You are threat hunting or triaging active exploitation. |
| **Decision Impact (Actionable Risk)** | The decision and impact signals (confidence, reachability, severity) | You are planning remediation or managing a vulnerability backlog. |
The profiles were renamed for clarity: Exploitation is now Exploitability, and Decision Impact is now Actionable Risk. The findings grid shows the current names. For the four signal groups and how each profile weights them, see [Binarly Risk Score](/resource-center/binarly-risk-score).
Switching profiles reorders the findings you already scanned. It does not change any underlying data or trigger a rescan, so you can move between profiles freely as your task changes.
![The Risk Score profile selector in the findings grid.]()
## Read the score
Each finding shows a risk score presented as a percentile. A higher percentile means more signals point to reachable, exploitable risk, so the finding deserves attention sooner. There are no fixed severity bands: you compare and sort on the score itself rather than mapping it to a label.
## Prioritize findings
The risk score is integrated in the findings grids: the global findings grid, the image findings grid, and finding sub-grids such as crypto findings. Each grid adds a Risk Score column and the profile selector above it. In the global and image findings grids, risk score is the default ordering metric, so findings open sorted by risk score, highest first, on the default Decision Impact (Actionable Risk) profile. Work the findings by risk:
Choose Balanced, Exploitability, or Actionable Risk from the Risk Score selector above the grid. The grid re-ranks in place.
The global and image findings grids are sorted by the Risk Score column by default, highest first. Re-sort or reverse the order from the column header if you need a different view.
Filter by risk score to focus on the top of the range while you remediate.
![The findings grid with the Risk Score column and profile selector.]()
## Related
* [Binarly Risk Score](/resource-center/binarly-risk-score) - the taxonomy groups, formula, profiles, and full metric reference.
* [Binarly Reachability Analysis](/resource-center/asap) - how reachability feeds the score.
* [EMS Escalations](/resource-center/ems-escalations) - the Exploitation Maturity Score.
* [Accuracy and confidence](/resource-center/accuracy-confidence) - how detection confidence is set.
# The Dashboard
Source: https://docs.binarly.io/user-guides/image-scans/the-dashboard
The Dashboard provides a high-level summary of the cumulative data within the Binarly Transparency Platform, functioning as a heads-up display for users. It is designed to offer an at-a-glance view of critical items, recent trends, and actionable insights, helping users prioritize review and remediation efforts efficiently.
## Key Features
1. Centralized Overview:
* Displays critical findings and trends from the most recent scans across all products.
* Highlights items requiring immediate attention to streamline decision-making.
2. Dynamic Graphs and Visualizations:
* Presents data in graphical formats for easy interpretation.
* Visualizations reflect the latest or most relevant scans of images, ensuring up-to-date insights.
3. Customizable Views:
* Tailor the dataset by applying filters for specific products, timelines, or other criteria.
* Drill down into graphs to access detailed information about individual findings or trends.
![]()
### Priority Findings
This graph details the high, critical, and medium severity findings across all products and images. It is designed to highlight the most pressing issues for investigation or remediation. The areas of the graph are interactive and can be used to sort or drill directly into a filtered finding page detailing the graphed data.
### Unknown Findings
This graph details and lists only unknown vulnerabilities discovered across all products and images. The graph is sorted by class of vulnerabilities, such as DXE Memory Corruption or SMM Memory Content Disclosure. Listed within these classes are the discovered unknown vulnerabilities. Unknown vulnerabilities have not been previously seen before and are technically zero-day. Drilling down into any portion of the graph will take you to a filtered list of the findings sorted by only unknown finding type.
### Threat Intelligence Monitoring
The Threat Intelligence Monitoring feature continuously tracks newly discovered vulnerabilities and emerging threats across your products. It automatically updates findings with real-time threat data from normalized vulnerability sources, without rescans. The following screenshot shows the Threat Intelligence Monitoring section.
![Threat Intelligence Monitoring widget on the dashboard]()
The Threat Intelligence Monitoring is powered by [Binarly Exploitation Maturity Score (EMS)](https://www.binarly.io/blog/the-hidden-danger-of-probabilistic-scoring-introducing-exploitation-maturity-score-ems). EMS uses [escalations](/resource-center/ems-escalations) such as exploit availability, activity, and maturity to accurately and transparently gauge the real-world risk of a vulnerability. The Threat Intelligence Monitoring section on the dashboard lists the top 10 vulnerabilities by EMS, along with the input escalations and impacted products. If two vulnerabilities have the same EMS, the EPSS of the vulnerability is used as a tie breaker (see below).
![Example of the Threat Intelligence Monitoring widget's sort order]()
This feature allows you to see the highest risk issues across your entire fleet at a glance and shows which products are affected. Clicking the section title redirects you to the full list of vulnerabilities for a more detailed look.
Users that have [notifications](/user-guides/advanced/notifications) enabled will automatically receive alerts when new EMS escalations occur for vulnerabilities in products they are subscribed to. The notification includes the vulnerability, the specific escalation that triggered the alert, and direct links to the affected product and image for immediate investigation.
### Findings by Age
Findings by age detail findings across all products and images listed by severity and sorted by the time the issues have existed but gone unaddressed or triaged. This representation is designed to provide visibility into the existing windows of risk based on the discovery timeline of the vulnerabilities. The graphs will trend with time and can be positively impacted by review and adjustment of the status of the findings represented in the graphs. Drilling down into the graph will take you to a filtered list of the findings sorted by Scan time ( discovery date) and status.
### Unreviewed Findings
The unreviewed findings graph details untriaged vulnerabilities by severity within the platform. This representation provides visibility into the remediation, mitigation, and documented review activity on discovered findings. It provides critical insights valuable for resourcing, utilization, and prioritization around the handling scan findings. All findings are marked with a status of new by default. When a Finding status is changed to in progress, rejected , or remediated, it is no longer unreviewed and does not show in this graph. Drilling into the graph will take you to a filtered list of the findings sorted by severity status and scan date.
### Findings in Products
Product findings offer a high-level visualization of the number of critical, high, and medium-severity vulnerabilities across the corpus of products analyzed by the platform. Expanding the individual products will give a breakdown of vulnerability counts by severity.
### Vulnerable External Dependencies
The vulnerable external dependencies graph represents a high-level overview of the statically linked and transitive dependencies discovered within the images analyzed by the platform. This important representation provides visibility of the true dependencies and components that make up the firmware, Linux packages, or containers analyzed by the platform. Hovering specific dependency names will provide visualizations of the versioning and counts of this particular dependency. Given this potentially large number of identified dependencies, details are available within each image under the dependencies tab.
### Trend of Findings by Severity
The finding trend visualization provides a customizable timeline view detailing vulnerability and finding discovery over time listed by severity. This view allows a user to spot and understand trends in discovery, mitigation, or remediation and triage issues. The customizable time frame slider allows closer inspection of particular trends and specific time ranges to understand better build time issues, Image scan events, resourcing, and incident response requirements.
## General Interface Navigation
The Binarly Transparency Platform interface is organized into distinct areas to facilitate efficient navigation and interaction. Beyond the dashboard, the interface includes menus, action/configuration sections, and navigational grid views to provide users with a streamlined experience.
### Menus
* Purpose: Menus serve as the primary navigation tool for accessing the platform's various capabilities and information.
* Location: Typically located along the top or side of the interface.
* Functionality:
* Direct access to key features such as Products, Findings, and Settings.
* Easy switching between different sections of the platform.
### Action and Configuration Sections
* Purpose: Allow users to interact with the platform by managing views, filters, and uploads.
* Locations:
* Bottom Left: Tools for creating new products or uploading images.
* Upper Right: Options to reset filters or change views.
* Dynamic Behavior: The available actions adjust based on the current platform view, ensuring context-appropriate options.
### Navigational Grid Views
* Primary Views: Products, findings, and scans are displayed within grid views designed for efficient review and management of information.
* Key Features:
* Customizable Columns: Tailor the grid to display only the information most relevant to your needs.
* Paginated Display: By default, grids show 50 items per page, with pagination options at the bottom center of the interface. Users can adjust the number of items displayed per page based on their preference.
* Organized Presentation: Grids are structured to provide a clear and concise overview of data at a glance.
* Action-Specific Columns: Columns and available actions vary depending on the grid you are viewing, ensuring the interface is tailored to the task at hand.
![]()
# Saved Views
Source: https://docs.binarly.io/user-guides/important-findings/saved-views
Important Findings are a feature of the Binarly Transparency Platform, allowing users to decide what is important to them.
Binarly defines some initial views of findings that we think are important, but the user can create and use whatever views matter to them.
## What are Saved Views
1. Saved views are a saved view of the Findings grid, so you can easily view findings that matter to you, they save:
* Any applied filters
* Any applied sorting
* Any column settings (column order, columns to display)
2. They are unique to each category of grid (Global, Product Image etc.):
* This means Custom Saved Views on the Global Findings grid are specific to the Global Findings
* Custom Saved Views on the Product Image Findings page are usable across all Product Images
![]()
## System Views
Binarly offer 5 system views by default, the "All" view and 4 others which are considered "Important Findings" unless the user
selects alternative views, these 4 other views are:
![]()
### CISA KEV
This view shows any findings that are also on CISA's Known Exploited Vulnerabilities list
This view displays all columns, with the following filters and sorting applied:
1. Filters
* Severity: Critical, High
* CISA KEV: Yes
* Type: All
* EPSS: Greater than 50%
2. Sorting
* Sorted by EMS descending first
* Sorted by EPSS descending second
### Malware
This view details findings related to malware
This view displays all columns, with the following filters and sorting applied:
1. Filters
* Type: All
* Finding Class: contains "malware"
2. Sorting
* Sorted by Severity descending
### Threat Intelligence
This view is a quick check against findings with escalations that could be considered severe
This view displays all columns, with the following filters and sorting applied:
1. Filters
* Severity: Critical, High, Unspecified
* Type: All
* EPSS: Greater than 50%
* EMS Escalations: All
2. Sorting
* Sorted by EMS descending first
* Sorted by EPSS descending second
### Validated Secrets
This view displays secrets that have been confirmed active through external API validation.
This view displays all columns, with the following filters and sorting applied:
1. Filters
* Type: Secret
* Validity: Valid
2. Sorting
* Sorted by Severity descending
## Custom Views
It is possible to setup custom views, which are the saved configuration of the grid including sorting, filters, and column settings
### Customising sorting
Setting sorting on the grid is done either directly against a column, or for more granular sorting can be done via the drawer.
When sorting on a column directly, it is only possible to set sorting against a single column at a time.
![]()
If sorting via the drawer, it is possible to setup up to five columns to sort against,
with the order of precedence set by the order the columns were selected.
!["An explanation of multi-sorting"]()
*In this example, results are sorted first by Severity, then SSVC, then CVSS, then EPSS, and lastly EMS*
### Customising filters
There are two ways to customise filters, either via the column headings, or via the drawer.
You can set individual filters against the column headings which will be applied immediately.
![]()
If changing settings via the drawer, you can change multiple things at once, and only apply upon confirmation by pressing the "Apply" button.
![]()
### Customising columns
Columns can be customised via the popover when pressing the Gear icon, and quickly adjusted here, these changes only take effect upon pressing apply.
![]()
![]()
Columns can also be customised via the drawer, in a subsection below the Filters section.
![]()
![]()
### Saving custom views
There are two ways to save new custom views.
* Duplicate: It is possible to duplicate any existing view, via the action menu against the View name.
This allows you to save a copy of the view with a distinct name and description.
* Save as new: At the bottom of the Saved Views menu there is an always available "Save as new"
which allows you to save the current view with a name and optional description.
* Updating an existing view: It is possible to update an existing view, rather than save it as new.
An Update button will appear on an active view when changes are made that differ to its existing configuration.
* Pro tip: A small green dot appears on the Saved Views menu whenever you are viewing a grid that likely has changes not saved to an existing view.
## Individual View actions
![]()
* Duplicate: As described above, allows the user to duplicate a view.
* Rename (disabled for System Views): Opens the modal to update the existing view, it is possible to
* Update the name of the view
* Update the description of the view
* Choose whether this view should be set as the default
(if you unset it as the default, the "All" view will automatically become the default)
* Use as Default: Sets the relevant view as the default view
* Delete (disabled for System Views): Opens modal to confirm deletion of the view
## What is the Default View
If you have not setup, or actively changed the default view, then it is the "All" view.
If you have chosen a default view, this view will be selected every time you visit the relevant Findings grid.
There are some caveats to this:
* Relevant view means a default in Global Findings will not be the default in Image findings,
this is set separately
* The default will not be selected if coming from a link that intends to show you something else.
For example, clicking a link from a widget on the dashboard may go to the Findings grid, but filtered to information relevant to the widget clicked
* If a view is not selected, this will be evident as the selected view is named in the Saved Views menu
# Widget
Source: https://docs.binarly.io/user-guides/important-findings/widget
The Important Findings widget by default uses the views defined by Binarly.
These are described in the previous section,
but the intent for this widget is that a user can decide what views are important to them,
and set it to show relevant information for them, using the Custom Saved Views they have defined.
## Where is it?
The widget can be found on the Dashboard and the Product Image Page.
On the Dashboard it will show total findings per selected view across all Findings.
If filtering the Dashboard by a product, it will filter findings to the first image found in that product.
![]()
## Controls
![]()
### 6 months or 12 months?
The widget by default displays a count of any findings of selected views in the last 6 months.
* There is a toggle on the widget to choose between 6 and 12 months
### Selecting custom views
There is a gear button which opens the settings for which views should display
* You can select up to 6 views
* If you have setup custom views, these will be displayed here
* Custom views display in context (Global Findings views on Dashboard,
Product Image views when Dashboard filtered by product or on product image)
* You can always use the "Reset" option to return the widget to its default state.
A red dot will appear on the gear when the views can be reset
![]()
### Excluding views temporarily
Selected views will display in the widget Legend
* Selecting the view name will disable / enable it displaying in the chart,
below the System View "Threat Intelligence" and the custom view "My Threat Intelligence (1)"
have been disabled
![]()
### Acting on the provided information
Go to the Global Findings grid or Product Image grid to get more detail on the findings
* Selecting the view slice in the bar chart will open to the relevant Findings grid filtered to that view
![]()
## Notes
* Custom views shown in the widget are specific to the category of Findings grid (Global, Product)
* The same finding may be found in multiple saved views depending on the filters selected
# Quotas
Source: https://docs.binarly.io/user-guides/rbac/quotas
Your BTP instance has a global limit on the number of unarchived Products your organization can have. This limit, called the **Organization Product Quota**, is set during your instance configuration.
You can distribute this quota to individual teams or keep it at the organization level. Any quota assigned to teams will be deducted from your total Organization Product Quota.
If you deplete or exceed this quota, you won't be able to create new products. However, all other functions, like uploading and scanning images, will still work.
## Creating a Product
When creating a new product, the quota it uses depends on your user permissions:
* **Team Admins** can create products that utilize their Team's allocated quota.
* **Organization Admins** and **Product Creators** can create products that utilize the overall Organization Quota.
![]()
## Setting Team Quota
To view or adjust a team's product quota:
* Navigate to **Organization > Teams**.
* Locate the desired team in the table.
* Hover over the three-dot menu (...) next to the team's name.
* Click "Update Quota".
![]()
## Viewing Team Quota
You can easily see the current quota usage for each team directly within the **Organization > Teams** table. The table provides a clear overview of how much product quota each team is currently utilizing.
![]()
## Viewing Organization Quota Usage
To see how much of your global Organization Quota has been utilized, visit the Organization page. This information is always accessible to users with appropriate viewing permissions.
![]()
## How Product Quota is calculated
* Only active (unarchived) products contribute to your product quota.
* If a team is deleted, all products previously associated with that team will then count towards the Organization Quota. And the Team's Quota is returned to the Organization.
# Roles
Source: https://docs.binarly.io/user-guides/rbac/roles
BTP uses **role-based access control** to manage what a user can see or do in the BTP. User roles are defined for Organization, Products and Teams.
## Organization Roles
In BTP, an organization is the highest-level entity. It acts as a container for all your Products, Users, and Teams. Think of it as the overarching structure that houses everything related to your work within BTP.
Within each organization, the following primary roles are available:
* **Organization Admin**: Organization Admins have the highest level of access and can manage all aspects of the organization. This includes:
* Managing users and their roles within the organization.
* Full access to all Products.
* Organizing [Teams](#team-roles) and inviting users to them.
* All other administrative functions within the organization.
* **Organization User**: This is the basic role assigned to all users within the organization. Their access to specific Products and features depends on the product roles assigned to them, either directly or through their Team memberships.
* **Product Creator**: This role has the same permissions as an *Organization User* but with the added ability to create new Products within the organization. Their access to and management capabilities within those products will then be determined by the product roles they are assigned.
* **Ruleset Creator**: This role allows users to create custom rulesets to be used in scanning images.
* **Guest**: A special role with a minimal level of access. Useful when giving an temporary access to a single Product and nothing else.
**Note**: An Organization can have multiple Organization Admins to share responsibilities, but there must be at least one to ensure proper management.
### Resource Roles at the Organization Level
In addition to the organization-specific roles, you can assign resource-specific roles at the organization level. This grants users the corresponding permissions on all resources of such type within the organization. For detailed information about the available roles and their specific permissions, see [Product Roles](#product-roles) and [Ruleset Roles](#ruleset-roles).
**Note**: Assigning such roles at the organization level can simplify access management by granting permissions across all resources at once. However, it's important to use this feature judiciously to avoid inadvertently granting excessive access.
Resource types that can have organization-level roles include:
* **Products**
* **Rulesets**
### Manage organization level roles
1. Go to the **Organization** page.
2. Navigate to the **Users** tab.
3. Select a user.
4. Click **Manage Roles**.
![]()
### Organization Permissions Table
| Permission | Organization Admin | Organization User | Product Creator | Ruleset Creator | Guest |
| --------------------------------------- | ------------------ | ----------------- | --------------- | --------------- | ----- |
| Manage Organization Access | ✅ | | | | |
| View Users | ✅ | ✅ | ✅ | | |
| Add/Remove Users | ✅ | | | | |
| View Teams | ✅ | ✅ | ✅ | | |
| Create Team | ✅ | | | | |
| Create Products | ✅ | | ✅ | | |
| View Custom Rules | ✅ | ✅ | ✅ | | |
| Create Rulesets | ✅ | | | ✅ | |
| Manage Organization Ruleset Deployments | ✅ | | | | |
| Manage Jira Integration | ✅ | | | | |
| Manage Team Quotas | ✅ | | | | |
## Team Roles
Teams streamline user management by allowing you to grant access to Products for a group of users at once. A single user can belong to multiple teams, providing flexibility in organizing your users.
Within each team, there are two distinct roles:
* **Team Admins** are members with elevated permissions, enabling them to manage the team itself. This includes adding or removing members and updating team details.
* **Team Members** are the individuals who have been invited to join the team.
Both roles have access to the Products assigned to the team.
![]()
### Team Permissions Table
| Permission | Team Admin | Team Member |
| --------------------------------- | ---------- | ----------- |
| Create new Products in Team Quota | ✅ | |
| Manage Team Access | ✅ | |
| View Team Members | ✅ | ✅ |
| Add/Remove Team Members | ✅ | |
| Remove Team | ✅ | |
| Rename Team | ✅ | |
| View Team Quotas | ✅ | |
## Product Roles
Product roles define specific levels of access to Products within an organization. These roles can be assigned at the Organization level (granting the role for all products), directly to users for a given product, or to an entire team for a given product.
Here's a breakdown of the product roles:
* **Product Admin**: Product Admins have the highest level of access to a product. They can manage access to the product by adding or removing users and teams.
* **Product Editor**: Product Editors can perform almost all actions within a product, except for managing access control (adding/removing users and teams) and archiving the product.
* **Product Viewer**: Product Viewers have read-only access to a product.
**Note**: If a user is added to a product individually and as part of a group, the higher role takes precedence.
![]()
### Product Permissions Table
| Permission | Product Admin | Product Editor | Product Viewer |
| ---------------------------------- | ------------- | -------------- | -------------- |
| Manage Product Access | ✅ | | |
| Archive/Unarchive Product | ✅ | | |
| Manage Product Ruleset Deployments | ✅ | | |
| Rename Product | ✅ | ✅ | |
| Upload Images | ✅ | ✅ | |
| Scan Images | ✅ | ✅ | |
| Archive/Unarchive Images | ✅ | ✅ | |
| Attach Symbols | ✅ | ✅ | |
| Generate Reports | ✅ | ✅ | ✅ |
| View Image Overview | ✅ | ✅ | ✅ |
| View Findings | ✅ | ✅ | ✅ |
| View Secrets | ✅ | ✅ | ✅ |
| View Dependencies | ✅ | ✅ | ✅ |
| View Cryptographic Materials | ✅ | ✅ | ✅ |
### Creating a new Product
Users with the following roles can create new products:
* Organization Admin
* Product Creator
## Ruleset Roles
Ruleset roles define specific levels of access to Rulesets within an organization. These roles can be assigned at the Organization level (granting the role for all rulesets), directly to users for a given ruleset, or to an entire team for a given ruleset.
* **Ruleset Admin**: Ruleset Admins have the highest level of access to a ruleset. They can manage access to the ruleset by adding or removing users and teams.
* **Ruleset Editor**: Ruleset Editors can perform almost all actions within a ruleset, except for managing access control.
* **Ruleset Viewer**: Ruleset Viewers have read-only access to a ruleset, including all revisions and files.
### Ruleset Permissions Table
| Permission | Ruleset Admin | Ruleset Editor | Ruleset Viewer |
| --------------------- | ------------- | -------------- | -------------- |
| Manage Ruleset Access | ✅ | | |
| Create new revision | ✅ | ✅ | |
| Edit rules | ✅ | ✅ | |
| View Revisions | ✅ | ✅ | ✅ |
| View Files | ✅ | ✅ | ✅ |
# Users
Source: https://docs.binarly.io/user-guides/rbac/user-management
This page provides information on managing users within your BTP organization. For details about organization-level roles and permissions, see [Organization Roles](/user-guides/rbac/roles#organization-roles).
## Inviting new Users
Organization Administrators can invite new users to the organization by email.
To invite a new user:
1. Go to the **Organization** page.
2. Navigate to the **Users** tab.
3. Enter the email address of the user you wish to invite.
4. Click **Invite**.
The invited user will receive an email with instructions on how to set up their account, including creating a password and enabling two-factor authentication (OTP).
![]()
## Single Sign-On (SSO)
For organizations that want to use existing identity providers for user authentication, BTP supports single sign-on (SSO) via OIDC and SAML. If you're interested in setting up SSO for your organization, please contact the Binarly Team.
With Single Sign-On (SSO) enabled, users can access BTP through an identity provider (IdP) of their choice.
# Deployments
Source: https://docs.binarly.io/user-guides/rule-management/deployments
Deploy Rulesets to run automatically on image scans at the organization or product level.
A Deployment connects a Ruleset to a scan scope. Once deployed, the Ruleset runs automatically on every new scan within that scope, and any matches appear as findings in the platform.
Deployments operate at two levels:
* **Organization** — the Ruleset runs on all image scans across the entire organization.
* **Product** — the Ruleset runs only on scans for a specific product.
Only **Organization Admins**, **Product Admins**, and **Rule Admins** can create or manage deployments.
## Creating a deployment
Navigate to **Rules → Rulesets** and select the Ruleset you want to deploy.
Click the **Deployments** tab on the Ruleset detail page. Existing deployments for this Ruleset are listed here.
![]()
Click **Deploy** and select the scope — organization-wide or a specific product. Confirm to activate the deployment.
## Findings from deployed Rulesets
When a deployed Ruleset matches during a scan, a finding is generated and appears in the **Findings** tab of the affected image. Each finding includes a **Detected with a custom rule** section that shows:
* The name of the Ruleset that produced the finding
* The specific rule within the Ruleset that matched
* The rule revision at the time of the match
![]()
Findings are linked to the rule revision that generated them. If the Ruleset is updated later, existing findings continue to reference the version of the rule that was active when the scan ran.
## Disabling a deployment
To stop a Ruleset from running on future scans, select the deployment from the Deployments tab and disable or delete it. Existing findings from previous scans are not removed.
# Custom Rule Manager
Source: https://docs.binarly.io/user-guides/rule-management/overview
Write, test, and deploy your own detection rules on the Binarly Transparency Platform.
The Custom Rule Manager lets you bring your own detection logic to the platform. You can write rules in the Playground, package them as Rulesets, and deploy them to run automatically during image scans.
## Workflow
The [Playground](/user-guides/rule-management/playground) is an interactive editor where you write rules and run them against images to see matches in real time. Use it to prototype and validate rules before packaging them.
A [Ruleset](/user-guides/rule-management/rulesets) is a collection of rules packaged as an OCI artifact and pushed to the Binarly Registry. Rulesets are versioned and can contain a mix of rule types.
A [Deployment](/user-guides/rule-management/deployments) attaches a Ruleset to an organization or a specific product. Once deployed, the Ruleset runs automatically on every new scan and any matches appear as findings in the platform.
## Supported rule types
YARA and FwHunt are the rule types you can write and deploy through the Custom Rule Manager. The rules that detect known vulnerabilities in identified components are [VulHunt](https://vulhunt-docs.binarly.io/user-guide/get-started/introduction) rules, which ship with the platform rather than being authored here. See [Component and Version Identification](/resource-center/component-identification) for how they run.
### YARA
[YARA](https://yara.readthedocs.io/) is a pattern-matching language widely used in malware research and threat intelligence. A YARA rule defines one or more strings — byte sequences, text patterns, or regular expressions — and a condition that must be true for the rule to fire. Rules can target any binary: executables, firmware images, libraries, or raw file blobs.
Use YARA when you need to:
* Hunt for known malware families or implants by signature
* Flag binaries containing specific imports, strings, or magic bytes
* Express complex multi-condition logic (e.g., "PE file AND contains these two strings AND file size under 1 MB")
See the [YARA documentation](https://yara.readthedocs.io/) for the full rule syntax and the [YARA GitHub repository](https://github.com/VirusTotal/yara) for source and issue tracking.
### FwHunt
[FwHunt](https://github.com/binarly-io/FwHunt) is Binarly's YAML-based rule format for UEFI firmware threat hunting. Rules match on UEFI module GUIDs, code patterns within firmware binaries, and firmware-specific characteristics. Because FwHunt is designed for firmware, it understands UEFI module structure natively — you can scope a rule to a specific module by GUID rather than scanning the entire image.
Use FwHunt when you need to:
* Detect known-bad UEFI implants or SMM callout patterns
* Match firmware modules by GUID with optional code-level conditions
* Write firmware-specific detections that would be impractical to express in YARA
See the [FwHunt specification](https://github.com/binarly-io/FwHunt) for the full rule format and the [FwHunt rule repository](https://github.com/binarly-io/FwHunt/tree/main/rules) for example rules.
## Roles and permissions
| Role | Capabilities |
| --------------- | ------------------------------------------------------------------------------ |
| **Rule Admin** | Create, edit, delete, and deploy Rulesets. Manage permissions for other users. |
| **Rule Editor** | Create and edit rules. Cannot deploy Rulesets. |
| **Rule Viewer** | Read-only access to rules and Rulesets. |
Organization Admins and Product Admins can manage deployments regardless of their rule-specific role. See [Roles](/user-guides/rbac/roles) for the full permissions matrix.
# Playground
Source: https://docs.binarly.io/user-guides/rule-management/playground
Interactively write and test detection rules against images before packaging them into a Ruleset.
The Playground is an interactive rule editor built into the platform. Write a rule, select images to test against, and see matches in real time — without needing to package or deploy anything first. Use it to prototype and validate rules before packaging them into a Ruleset.
## Accessing the Playground
Navigate to **Rules → Playground** in the left sidebar.
![]()
## Interface overview
The Playground is split into three panels:
* **File Explorer** (left) — browse your Rulesets and the individual rules within them. Selecting a rule loads it into the editor.
* **Code Editor** (center) — write and edit your rule. The editor auto-detects the rule format (YARA or FwHunt) as you type, and provides live syntax highlighting, linting, and inline error markers.
* **Test Images and Results** (right) — select images to test against or upload new ones, then view match results after running the scan.
![]()
## Live linting
The editor checks your rule continuously as you type. Syntax errors and lint warnings appear inline and in the margin without needing to trigger a scan. A rule with errors cannot be scanned until the issues are resolved.
## Testing against images
You can test against:
* **Images already in the platform** — select any image from products you have access to using the image search dropdown.
* **Uploaded test images** — upload a file directly in the Playground. Test images are session-only: they are not added to any product, not visible to other users, and are discarded when the session ends.
Once at least one image is selected and the rule has no errors, click **Scan** in the top right to run the rule. Results appear in the Results tab.
## Reading scan results
Results are grouped by image. For each image, the results show:
* Components where the rule matched
* Build environment details for matched binaries
* Code listing showing the location of the match with surrounding context
* Hex dump of the matched bytes
![]()
Scan results in the Playground are temporary. They are not added to the product findings and are not visible to anyone else. To generate persistent findings, [deploy the Ruleset](/user-guides/rule-management/deployments).
You can only select images from products your account has permission to access.
# Rulesets
Source: https://docs.binarly.io/user-guides/rule-management/rulesets
Package and push your detection rules to the Binarly Registry as OCI artifacts.
A Ruleset is a collection of detection rules packaged as an OCI artifact and stored in the Binarly Registry. Rulesets are the unit of deployment — you deploy Rulesets, not individual rules. A Ruleset can contain YARA rules, FwHunt rules, or a mix of both.
## Prerequisites
Rulesets are pushed using [oras](https://oras.land/) (OCI Registry As Storage), a CLI tool for pushing and pulling OCI artifacts. Install it before proceeding:
```bash theme={null}
brew install oras
```
```bash theme={null}
VERSION="1.2.0"
curl -LO "https://github.com/oras-project/oras/releases/download/v${VERSION}/oras_${VERSION}_linux_amd64.tar.gz"
sudo tar -zxf oras_${VERSION}_linux_amd64.tar.gz -C /usr/local/bin oras
```
Check the [oras releases page](https://github.com/oras-project/oras/releases) for a newer version before installing.
```powershell theme={null}
winget install oras
```
## Directory structure
Organize your rules in a directory before pushing. You can use any folder structure — oras will push the entire directory tree as a single artifact.
```
my-ruleset/
├── yara/
│ ├── threat_hunting.yar
│ └── supply_chain.yar
└── fwhunt/
├── smm_callouts.yaml
└── uefi_implants.yaml
```
Rules do not need to be separated by type, but grouping them makes the Ruleset easier to navigate in the Playground.
## Writing rules
YARA rules follow the standard YARA format. This example detects an embedded PE file with a suspicious import:
```yara theme={null}
rule SuspiciousEmbeddedPE : firmware
{
meta:
description = "Detects embedded PE with remote thread creation capability"
author = "security-team"
date = "2026-01-01"
strings:
$mz = { 4D 5A }
$remote_thread = "CreateRemoteThread" wide ascii
$debug_priv = "SeDebugPrivilege" wide ascii
condition:
$mz at 0 and any of ($remote_thread, $debug_priv)
}
```
See the [YARA documentation](https://yara.readthedocs.io/) for the full rule syntax.
FwHunt rules are YAML-based and target UEFI firmware binaries. This example matches a module by its GUID and checks for a known-bad code pattern:
```yaml theme={null}
name: FWHUNT_EXAMPLE_SMM_CALLOUT
version: "1.0"
description: "Detects SMM callout via NVRAM variable in a specific module"
rules:
- rule:
guid: "7C436110-AB2A-4BBB-A880-FE41995C9F82"
strings:
- name: callout_pattern
value: "GetVariable"
wide: false
condition: any
```
See the [FwHunt documentation](https://github.com/binarly-io/FwHunt) for the full rule specification.
## Pushing a Ruleset
Your registry hostname is derived from your platform URL. If your platform is at `app.{instance}.binarly.cloud`, your registry is at `registry.{instance}.binarly.cloud`. For example, if you access the platform at `app.i7sydgb4.binarly.cloud`, your registry hostname is `registry.i7sydgb4.binarly.cloud`.
Use your Binarly account email and password.
```bash theme={null}
oras login registry.{instance}.binarly.cloud -u your@email.com -p
```
From the parent directory of your rules folder, push its contents to the registry. Use a meaningful name and tag to identify the Ruleset version.
```bash theme={null}
oras push registry.{instance}.binarly.cloud/:latest ./my-ruleset/
```
To tag a specific version instead of overwriting `latest`:
```bash theme={null}
oras push registry.{instance}.binarly.cloud/:v1.2.0 ./my-ruleset/
```
After a successful push, the Ruleset appears in **Rules → Rulesets**. From there you can open it in the [Playground](/user-guides/rule-management/playground) to test individual rules, or [deploy it](/user-guides/rule-management/deployments) to run on scans.
## Updating a Ruleset
Push to the same name with an updated tag. The platform tracks Ruleset versions — previous versions remain accessible and findings already generated from them are linked to the rule revision that produced them.
```bash theme={null}
# Update the latest tag
oras push registry.{instance}.binarly.cloud/:latest ./my-ruleset/
# Or tag a new explicit version
oras push registry.{instance}.binarly.cloud/:v1.3.0 ./my-ruleset/
```
Findings generated from an earlier version of a Ruleset remain visible and continue to link to the specific rule revision that produced them, even after the Ruleset is updated.
## Other useful commands
### List Rulesets
```bash theme={null}
oras repo ls registry.{instance}.binarly.cloud
```
### List tags
```bash theme={null}
oras repo tags registry.{instance}.binarly.cloud/
```
### Pull a Ruleset
Download a Ruleset to inspect or modify it locally:
```bash theme={null}
oras pull registry.{instance}.binarly.cloud/:v1.2.0 -o ./my-ruleset/
```
### Re-tag without re-pushing
Promote a specific version to `latest` without uploading the files again:
```bash theme={null}
oras tag registry.{instance}.binarly.cloud/:v1.2.0 latest
```
### Log out
```bash theme={null}
oras logout registry.{instance}.binarly.cloud
```