immunefi-cli

Unofficial CLI for Immunefi's bug bounty platform. Immunefi has no official API — this tool reverse-engineers their web app's HTTP APIs to provide programmatic access to report management.

Why this exists

The proliferation of AI-assisted security tools has led to a ~10x increase in bug bounty report volume. Most of these reports come from new accounts with zero prior successful findings — they read as plausible but are often deeply mistaken: not actually bugs, based on misunderstandings of the protocol, duplicates of known issues, etc. But legitimate findings still come through, so every report needs to be taken seriously.

This CLI enables an AI-first triage layer: an agent reads incoming reports, assesses them, posts responses, and updates statuses — while a human reviews the agent's work. The result is the same coverage with a fraction of the maintenance burden.

Built for LLM agents first (-o json / -o yaml), humans second.

Disclaimer: This is an unofficial tool and is not affiliated with or endorsed by Immunefi. Use at your own risk. Immunefi may change their APIs at any time, which could break this tool.

Installation

# From npm
npm install --global @hyperlane-xyz/immunefi-cli

# Or with pnpm
pnpm add --global @hyperlane-xyz/immunefi-cli

# From source
git clone https://github.com/hyperlane-xyz/immunefi-cli.git
cd immunefi-cli
pnpm install
pnpm build
pnpm link --global  # makes `immunefi` available globally

Releases are published from GitHub Actions via npm trusted publishing (OIDC).

Quick Start

1. Configure credentials

Create ~/.immunefi-cli/credentials.yaml:

email: [email protected]
password: "your-password"
totpSecret: YOUR_BASE32_TOTP_SECRET

Or use environment variables:

export [email protected]
export IMMUNEFI_PASSWORD=your-password
export IMMUNEFI_TOTP_SECRET=YOUR_BASE32_TOTP_SECRET

2. Log in

immunefi login

This authenticates via Firebase + TOTP MFA, discovers your projects, and saves the session (~8h TTL) and project config to ~/.immunefi-cli/.

Logged in as your_username ([email protected])
Session expires: 2026-04-08T04:13:32.000Z
Using project: YourProject (programId: 547, orgId: 888)
  (defaulted to first project — 1 project available)

3. Use it

# List all escalated reports
immunefi reports --status escalated

# Show a specific report with full description + activity
immunefi report 72385

# Post a comment
immunefi comment 72385 "Thanks for the report, we're investigating."

# Or from a file
immunefi comment 72385 --file response.md

# Change report status
immunefi update-status 72385 --status closed --message "Closing as not a bug."

Example output

These are not real reports 😛

$ immunefi reports --status escalated --limit 4

ID      Status      Severity  Reporter            Created     Title
────────────────────────────────────────────────────────────────────────────────────────────
71823   escalated   critical  security_res_42     2026-04-01  Reentrancy in withdraw() allows draining of vault funds
71790   escalated   high      whitehat_99         2026-03-31  Missing access control on setOracle permits price manipulation
71654   escalated   medium    auditor_abc         2026-03-29  Off-by-one in fee calculation leads to 0.01% underpayment
71512   escalated   low       bugfinder_7         2026-03-28  Misleading error message in CLI tool

$ immunefi report 71823

Report #71823 — Reentrancy in withdraw() allows draining of vault funds
Status: escalated | Severity: critical | Type: smart_contract
Reporter: security_res_42 (intermediate) | Created: 2026-04-01
Has PoC: yes

--- Description ---
## Summary

A reentrancy vulnerability in `Vault.withdraw()` allows an attacker to
drain all funds by re-entering during the external call before the
balance update...

--- Activity (3 events) ---
[2026-04-01 14:22] report_created by security_res_42
[2026-04-01 14:30] message_created by Automated Filter (Immunefi Bot): "Hi, Thanks for the submission..."
[2026-04-01 15:01] status_updated by Automated Filter (Immunefi Bot): reported → escalated

Output Formats

All commands support -o / --output:

• human (default) — colored, tabular output for terminals
• json — full structured JSON, ideal for LLM agents and programmatic consumption
• yaml — full structured YAML, no truncation

# Machine-readable report list
immunefi reports --status escalated -o json

# Pipe to other tools
immunefi report 72385 -o json | jq '.report.description'

Commands

| Command | Description | |---------|-------------| | immunefi login | Authenticate and save session + project config | | immunefi reports | List reports (auto-paginates all pages) | | immunefi report <id> | Show report detail + events | | immunefi comment <id> [body] | Post a comment on a report | | immunefi update-status <id> | Change a report's status with a message | | immunefi llm-docs | Print complete LLM agent reference (no auth required) |

immunefi reports

Options:
  -s, --status <status>  Filter: escalated, confirmed, closed, paid, reported
  -l, --limit <n>        Max number of results

immunefi report <id>

Options:
  --no-events  Skip fetching events/comments

immunefi comment <id> [body]

Options:
  -f, --file <path>        Read body from file
  --stdin                  Read body from stdin
  --audience <audience>    Comment audience (default: all_subscribers)

immunefi update-status <id>

Options:
  -s, --status <status>    Target status (required)
  -m, --message <body>     Message to include (required)
  --message-file <path>    Read message from file
  --template <id>          Template UUID

immunefi llm-docs

Prints a complete LLM agent reference document to stdout. No authentication required. Designed as the single entrypoint for AI agents to learn how to use this CLI.

# Feed to an LLM agent as context
immunefi llm-docs

# Pipe into a file for inclusion in prompts
immunefi llm-docs > /path/to/immunefi-reference.md

The output includes:

• Safety rules (what never to include in comments)
• All commands with auto-generated flag documentation
• Output schemas (Report, ReportDetail, ReportEvent field types)
• Immunefi domain concepts (statuses, severity, SLAs, event types)
• Common workflows (triage, close, confirm, pay)

Configuration

Credential Resolution

Credentials are resolved in priority order (highest wins):

1. CLI flags (--email, --password, --totp-secret)
2. Environment variables (IMMUNEFI_EMAIL, IMMUNEFI_PASSWORD, IMMUNEFI_TOTP_SECRET)
3. Config file (~/.immunefi-cli/credentials.yaml)

The config file path can be overridden with --config <path> or IMMUNEFI_CONFIG env var.

Project Selection

On login, the CLI discovers available projects from your Immunefi account. If you have multiple projects, it defaults to the first one. Override with --program-id <id> or IMMUNEFI_PROGRAM_ID env var.

The selected project is saved to ~/.immunefi-cli/project.yaml and used for subsequent commands.

Global Options

-o, --output <format>    Output format: human (default), json, or yaml
--email <email>          Immunefi email
--password <password>    Immunefi password
--totp-secret <secret>   TOTP secret
--config <path>          Path to credentials.yaml
--program-id <id>        Program ID override

Authentication Details

Immunefi uses Firebase Auth with app-level TOTP MFA. The login flow:

1. Bootstrap CSRF token from bugs.immunefi.com
2. Firebase signInWithPassword (may trigger Firebase-level MFA)
3. Exchange Firebase token for Immunefi session cookie
4. App-level TOTP verification if required

Sessions are persisted to ~/.immunefi-cli/session.yaml and auto-refresh when expired.

Development

pnpm install
pnpm build            # compile TypeScript
pnpm test             # unit tests (no network)
pnpm test:integration # live API tests (needs credentials)
pnpm lint             # biome check
pnpm lint:fix         # biome autofix

Integration Tests

Integration tests hit the real Immunefi API (read-only, no mutations). They require credentials and are skipped by default:

IMMUNEFI_INTEGRATION=1 pnpm test:integration

License

Apache 2.0 — see LICENSE.