> ## Documentation Index
> Fetch the complete documentation index at: https://vulhunt-docs.binarly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

The CLI tool scans binaries and firmware for vulnerabilities, serves an MCP endpoint for AI-assisted analysis, and integrates with the Binarly Transparency Platform (BTP).

NOTE: we show usage via the community edition tool, for enterprise customers, use `vulhunt`.

## Scanning binaries

### Single rule

Scan a binary with a single rule and display results in the terminal:

```shell theme={null}
vulhunt-ce scan \
  --data ./bias-data \
  --rules CVE-2024-6387.vh \
  --output results.json \
  --pretty \
  ./sshd
```

The above command uses the rule `CVE-2024-6387.vh` to scan the `sshd` binary. Type libraries and signatures are loaded from `./bias-data`, which should contain the required [Auxiliary Data](/user-guide/vulhunt-cli/auxiliary-data). Results are written to `results.json` and rendered to the terminal with `--pretty`.

### Rule set

Scan a binary against all rules in a directory:

```shell theme={null}
vulhunt-ce scan \
  --data ./bias-data \
  --rules ./my-rules/ \
  --output results.json \
  --pretty \
  ./sshd
```

When scanning with multiple rules, narrow down rule coverage with [Conditions](/vulhunt-reference/vulhunt-rules/rule-fields#conditions) to minimize the performance impact.

### UEFI firmware and alternate loaders

Scan a UEFI firmware image using the `uefi` loader:

```shell theme={null}
vulhunt-ce scan \
  --loader uefi \
  --data ./bias-data \
  --rules ./uefi-rules/ \
  --output results.json \
  --pretty \
  ./firmware.bin
```

VulHunt's scanner also supports `ba2` (Binarly Analysis Archive) and `bndb` (Binary Ninja) loaders. The Binary Ninja loader requires VulHunt to be built with [specific support](/user-guide/vulhunt-cli/installation#integrations).

### Component attributes

Pass additional metadata when scanning individual components:

```shell theme={null}
vulhunt-ce scan \
  --data ./bias-data \
  --rules ./my-rules/ \
  --component-attribute kind=SmmModule \
  --component-attribute guid=FEAB1234-5678-90AB-CDEF-1234567890AB \
  --output results.json \
  --pretty \
  ./module.efi
```

### Streaming output

For CI/CD pipelines or large scans, stream results as JSONL:

```shell theme={null}
vulhunt-ce scan \
  --data ./bias-data \
  --rules ./my-rules/ \
  --output results.jsonl \
  --stream \
  ./firmware.bin
```

Add `--compress` to compress the stream with Zstandard:

```shell theme={null}
vulhunt-ce scan \
  --data ./bias-data \
  --rules ./my-rules/ \
  --output results.jsonl.zst \
  --stream --compress \
  ./firmware.bin
```

### Using environment variables

Set common paths once and omit them from individual commands:

```shell theme={null}
export BIAS_DATA=./bias-data
export BIAS_VULHUNT_RULES=./my-rules

vulhunt-ce scan --output results.json --pretty ./sshd
```

## Starting the MCP server

The `mcp` subcommand starts a Model Context Protocol server for AI-assisted binary analysis.

### HTTP transport

```shell theme={null}
vulhunt-ce mcp --data ./bias-data --host 0.0.0.0 --port 9090
```

### Stdio transport

For integration with tools like Claude Desktop:

```shell theme={null}
vulhunt-ce mcp --data ./bias-data --stdio
```

## Binarly Transparency Platform (BTP)

The `btp` subcommand interacts with the Binarly Transparency Platform. All commands require authentication credentials, which can be passed as options or set via environment variables:

```shell theme={null}
export BTP_USERNAME=user@example.com
export BTP_PASSWORD=your-password
export BTP_INSTANCE_SLUG=your-org.prod
```

### Pushing rules

Push a rule pack from local directories to BTP:

```shell theme={null}
vulhunt-ce btp push-rules \
  -r rulepacks/custom \
  --name "My Custom Rules" \
  ./posix/ ./uefi/
```

Push and deploy directly to a product:

```shell theme={null}
vulhunt-ce btp push-rules \
  -r rulepacks/custom \
  --deploy-to-product 01JQXYZ1234567890ABCDE \
  ./posix/ ./uefi/
```

Push individual rule files (requires `--platform`):

```shell theme={null}
vulhunt-ce btp push-rules \
  -r rulepacks/custom \
  --platform posix \
  CVE-2024-6387.vh CVE-2025-1234.vh
```

### Managing products

List all products:

```shell theme={null}
vulhunt-ce btp list-products
```

Create a new product:

```shell theme={null}
vulhunt-ce btp create-product \
  --name "Router Firmware" \
  --description "Production router firmware images"
```

### Uploading and scanning

Upload a firmware image and trigger a scan:

```shell theme={null}
vulhunt-ce btp upload \
  --product-id 01JQXYZ1234567890ABCDE \
  --name "Router v2.1" \
  --version "2.1.0" \
  --scan \
  ./firmware.bin
```

### Monitoring scans

List scans for an image:

```shell theme={null}
vulhunt-ce btp list-scans \
  --product-id 01JQXYZ1234567890ABCDE \
  --image-id 01JQXYZ1234567890FGHIJ
```

Get scan details:

```shell theme={null}
vulhunt-ce btp get-scan \
  --product-id 01JQXYZ1234567890ABCDE \
  --image-id 01JQXYZ1234567890FGHIJ \
  --scan-id 01JQXYZ1234567890KLMNO
```

### Retrieving results

Get findings for an image:

```shell theme={null}
vulhunt-ce btp get-findings \
  --product-id 01JQXYZ1234567890ABCDE \
  --image-id 01JQXYZ1234567890FGHIJ
```

Download a BA2 archive for offline analysis:

```shell theme={null}
vulhunt-ce btp download-ba2 \
  --product-id 01JQXYZ1234567890ABCDE \
  --image-id 01JQXYZ1234567890FGHIJ \
  -o ./image.ba2
```

## Querying BA2 archives

The `ba2` subcommand inspects and extracts components from Binarly Analysis Archives.

### Listing components

```shell theme={null}
vulhunt-ce ba2 list-components ./image.ba2
```

### Extracting a component

```shell theme={null}
vulhunt-ce ba2 extract-component \
  --component-id 550e8400-e29b-41d4-a716-446655440000 \
  -o ./extracted-module.efi \
  ./image.ba2
```