Opena2a CLI

What is Opena2a CLI about?

Opena2a CLI is a single‑command security assessment tool that inspects AI projects for credential exposure, hidden agents, insecure configurations and other vulnerabilities across the entire OpenA2A toolchain. It produces a quantitative security score and links each finding to the specialized sub‑tool that can resolve it.

How to use Opena2a CLI?

# Run a read‑only assessment (no installation required)
npx opena2a-cli init my-agent

# Apply automatic fixes based on the assessment
npx opena2a-cli protect my-agent

# Generate a full interactive report (downloads NanoMind model on first run)
npx opena2a-cli review my-agent    # add --no-open to suppress the browser

Installation options:

• npx (no install) – use the commands above directly.
• Global npm install – npm install -g opena2a-cli and then run opena2a ....
• Homebrew – brew install opena2a-org/tap/opena2a.
• From source – clone the monorepo, run npm install && npm run build, then execute ./packages/cli/dist/index.js.

Key Features of Opena2a CLI

• Credential leak detection – finds hard‑coded API keys, passwords, and other secrets.
• Shadow AI discovery – identifies undeclared agents, MCP servers and AI config files.
• One‑click remediation – protect migrates secrets to environment variables, adds .gitignore rules, signs configs, and creates rollback manifests.
• Delegated sub‑tools – integrates with hackmyagent (static/semantic scanning), secretless-ai (runtime secret injection), and ai-trust (registry trust checks).
• Identity & audit – built‑in AIM identity creation, local append‑only JSONL audit log, and trust scoring.
• Self‑hosted or cloud AIM – offline mode works out‑of‑the‑box; optional cloud or Docker‑based AIM server adds real‑time enforcement and dashboards.
• Provenance & supply‑chain security – all releases published with SLSA v1 attestations via npm Trusted Publishing.
• Natural‑language command discovery – type plain phrases like opena2a "find leaked credentials" to get the matching command.
• Extensible workflow – supports CI/CD integration, benchmark against OASB attack scenarios, and custom policy hooks.

Use Cases of Opena2a CLI

Audience	Scenario
Developer using AI coding tools	Run npx opena2a-cli init . before committing code to catch hard‑coded keys and mis‑configured agent files (≈5 min).
Security team assessing fleet risk	Scan multiple repos or MCP servers with opena2a scan <target> and aggregate scores across the organization (≈10 min).
MCP server author	Validate that the server’s configuration, identity and secret handling meet governance standards via opena2a protect and opena2a shield init (≈15 min).
CI/CD pipeline	Add npx opena2a-cli init and npx opena2a-cli protect steps to CI jobs; fail the pipeline on CRITICAL findings.

FAQ from the Opena2a CLI

• Do I need to install anything first? No. All commands work via npx which downloads the latest package on demand. For repeated use you can npm install -g opena2a-cli.

• What Node version is required? Node.js 18 or later.

• How are findings automatically fixed? The protect command rewrites hard‑coded secrets to environment‑variable references, adds appropriate .gitignore entries, signs configuration files and creates a rollback manifest.

• Where are audit logs stored? Local append‑only JSONL file at ~/.opena2a/aim-core/audit.jsonl. Rotation occurs at 50 MiB with the last five generations retained.

• Can I run the tool without internet access? Yes. All core scanning works offline. Only the first review run (which downloads the NanoMind model) and optional cloud AIM features require connectivity.

• How do I verify the npm package provenance? Use npm view opena2a-cli dist.attestations --json to see the SLSA provenance predicate, and npm audit signatures to check the registry signatures.

• What if I want to self‑host the AIM identity service? Clone the agent-identity-management repository and run the provided quickstart.sh Docker stack. Then invoke CLI commands with --server <url> to point to your instance.

• Which sub‑tool handles a specific vulnerability? The CLI prints a “Fix:” hint for each finding, e.g., Fix: opena2a protect for credential leaks, or delegates to hackmyagent, secretless-ai, or ai-trust as appropriate.

opena2a-cli

OpenA2A: CLI · HackMyAgent · Secretless · AIM · Browser Guard · DVAA

Unified CLI for the OpenA2A security toolchain. One command finds credential leaks, shadow AI, unsigned configs, and ungoverned agents, then fixes them. Apache 2.0.

Website · Docs · Demos · Discord

Quick start

npx opena2a-cli init my-agent      # 1. read-only assessment: every finding prints Verify and Fix
npx opena2a-cli protect my-agent   # 2. apply the fixes
npx opena2a-cli review my-agent    # 3. full report. First run downloads the NanoMind
                                   #    model files; --no-open skips the browser.

What init prints (captured from opena2a-cli 0.10.13 on a small demo project, trimmed):

  OpenA2A Security Assessment  v0.10.13         0.1s

  Project      acme-agent v2.1.0
  Stack        Node.js + MCP server

  Findings
  -----------------------------------------------
  CRITICAL  OpenAI API Key
            OpenAI API key hardcoded in source. Grants full API access
            to anyone with the source code.
            src/agent.js:1
            Verify: sed -n '1p' src/agent.js
            Fix:    opena2a protect
  ...
  Security Score: 62 / 100  (project posture: credentials, config, environment)

Install

npm

npx opena2a-cli init my-agent   # run once, no install
npm install -g opena2a-cli      # install globally

Requires Node.js 18 or later.

Homebrew

brew install opena2a-org/tap/opena2a

From source

This repo is a TypeScript turborepo. Clone and build if you want to inspect the source, contribute, or run an unreleased version.

git clone https://github.com/opena2a-org/opena2a.git
cd opena2a
git verify-tag $(git describe --tags --abbrev=0)   # verify the latest release tag
npm install
npm run build                                      # builds all workspaces via turbo
./packages/cli/dist/index.js review                # run the freshly-built binary

# Or link it globally for the current shell:
cd packages/cli && npm link
opena2a review

The workspaces. packages/cli is the binary; the rest are libraries it consumes.

packages/
├── cli                  the opena2a binary
├── aim-core             local-first identity, audit log, policies
├── check-core           scanner orchestration
├── cli-ui               shared render primitives
├── credential-patterns
├── registry-client
├── ai-classifier
├── telemetry
├── contribute           skill scaffolding
└── shared               types + utilities

The CLI also depends on three sister packages published from their own repos (declared as runtime deps in packages/cli/package.json): hackmyagent, secretless-ai, and ai-trust. opena2a scan delegates to hackmyagent. opena2a secrets delegates to secretless-ai. opena2a trust queries via ai-trust.

Verifying what was installed

Every version from 0.8.24 on has been published from GitHub Actions through npm Trusted Publishing, with SLSA v1 provenance; earlier versions carry no attestation. The publishing workflow references no npm token; GitHub Actions exchanges its OIDC token with npm at publish time. The command below prints, without verifying anything, the provenance type and attestation URL the registry lists for the latest opena2a-cli (append @<version> for another; an unattested version prints nothing). npm audit signatures checks the registry's signatures and attestations for installed versions, not the installed files or who built them, and does not flag a version without an attestation.

npm view opena2a-cli dist.attestations --json
# Expects non-empty result with predicateType "https://slsa.dev/provenance/v1"

For local CLI integrity (post-install tamper), opena2a status reports the binary signature state. opena2a shield selfcheck runs the full self-attestation against the embedded manifest.

Identity files (~/.opena2a/aim-core/identity.json) are written mode 0600. OAuth tokens live in the OS keychain by default. ~/.opena2a/auth.json stores metadata only.

Which OpenA2A CLI do I want

There are four published CLIs in the toolchain. opena2a is the unified front door. Each underlying tool can also be installed and run standalone if that fits better.

You want to...	Use	Standalone install
Run one command and get a security assessment of your project	opena2a init	(front door)
Scan a specific MCP server, skill, npm package, or GitHub repo	opena2a scan <target> or hackmyagent check <target>	npm install -g hackmyagent
Wrap any subprocess with credentials injected at runtime	opena2a secrets run --only KEY -- <cmd> or secretless-ai run --only KEY -- <cmd>	npm install -g secretless-ai
Check the trust posture of an npm or PyPI package before installing	opena2a trust <pkg> or ai-trust <pkg>	npm install -g ai-trust
Give your agent a cryptographic identity and local audit log, no server	opena2a identity create --name X	(bundled in opena2a-cli)
Benchmark a security tool against the OASB attack scenarios	opena2a benchmark	(uses OASB internally)

If you're not sure where to start, run opena2a init in your project root. It tells you what's wrong and which underlying tool to invoke for the fix.

Built-in help

opena2a ~shadow ai                     # semantic search ("ai" finds AI-related commands)
opena2a "find leaked credentials"      # natural language to matched command
opena2a                                # interactive guided wizard (no args)

Commands

Three job categories: assess, protect, operate. Run any with --help for full flags.

Assess

Command	What it does
opena2a init	Read-only security assessment with a trust score for your project. Start here.
opena2a review	Full security dashboard. 6-phase assessment, HTML report. First run downloads the NanoMind model files; --no-open skips the browser.
opena2a detect	Shadow AI discovery. Finds undeclared agents, MCP servers, AI configs. Returns a governance score.
opena2a scan <target>	Static, semantic, and adversarial-payload checks via HackMyAgent (current counts: hackmyagent --help). Targets: local repo, npm package, GitHub repo, MCP server, skill, or standalone SOUL.md.
opena2a check <target>	Pre-install trust check. Queries the OpenA2A Registry and runs HMA locally.
opena2a scan-soul <path>	Governance controls across every ABGS domain, profile-aware.
opena2a trust <pkg>	Read-only Registry lookup for an npm or PyPI package.
opena2a benchmark	Run the OASB benchmark against your security tool.

Protect

Command	What it does
opena2a protect	Migrate hardcoded credentials to env-var references, masked previews, rollback manifest. Adds .gitignore patterns. Signs configs.
opena2a harden-soul	Generate a SOUL.md governance file from your project state.
opena2a harden-skill <path>	Frontmatter validation, permission scoping, integrity pinning on a Claude or Cursor skill.
opena2a guard sign	Sign and watch config files (mcp.json, claude_desktop_config.json, etc.). Alerts on unauthorized changes.
opena2a shield init	One-shot 11-step setup: review, protect, identity, guard, secrets, runtime, policy, hooks.

Optional AAP gate on protect

protect can be gated by the Agent Authorization Protocol. When --grant is set, the CLI presents an ATX and a grant reference to the local Secretless broker before any scan runs. The broker is the policy decision point; the CLI proceeds only if the broker authorizes.

opena2a protect \
  --grant grant://opena2a-protect \
  --atx ~/.opena2a/atx.json

Outcomes:

• Broker authorizes -> protect proceeds.
• Broker denies (HTTP 403) -> protect exits 3 with a one-line pointer to ~/.secretless-ai/policies/. Per AAP §6.6 the denial is opaque; reasons live only in the broker's signed audit log.
• Broker unreachable -> protect exits 4 with a secretless broker start hint.
• Broker returns an unexpected status -> protect exits 6. The response body is never echoed to the user; reasons live only in the broker audit log.
• No --grant flag -> protect runs exactly as before; the gate is opt-in.

This integration newly defends T-3002 (cross-tenant grant leakage), T-3003 (over-broad credential scope), T-3006 (credential leaking into agent context), and T-8002 (audit attribution gap) at the CLI surface. The broker is the integrity-protected decision and audit point; the CLI carries no policy state.

Operate

Command	What it does
opena2a identity create --name X	Generate an Ed25519 keypair locally. Writes ~/.opena2a/aim-core/identity.json.
opena2a identity integrate	Wire up cross-tool bridges so Secretless, HMA, ConfigGuard, Shield, and ARP events flow into one unified audit log.
opena2a identity audit [--limit N]	Read back the unified audit log. The query path for incident response.
opena2a identity trust	Local 8-factor posture score.
opena2a identity sign --data X	Sign arbitrary bytes with the agent's Ed25519 key.
opena2a runtime tail [-c N]	Tail the HMA ARP runtime event stream for the current project.
opena2a secrets ...	Credential management via Secretless. add, list, run, revoke.
opena2a mcp ...	MCP server lifecycle: audit, sign, verify.
opena2a status	What's running, what's protected, what's missing.
opena2a login	OAuth 2.0 device flow against AIM Cloud or your self-hosted server.
opena2a whoami	Current auth status.
opena2a skill create <name>	Scaffold a new secure skill with signing and heartbeat.
opena2a train	Boot DVAA, the deliberately vulnerable AI agent, for security training.

Full command reference: opena2a.org/docs.

Post-incident review

Once opena2a identity integrate runs once, every event the OpenA2A toolchain captures auto-bridges into a single local audit log. No decorator in your agent code. No server. When something goes wrong:

opena2a identity audit --limit 200
# 200 most recent events: credential injections, file accesses, config
# changes, scan findings, ARP runtime events. All in one timestamp-
# ordered JSON-lines view, sourced from Secretless, HackMyAgent,
# ConfigGuard, Shield, and ARP.

opena2a identity audit | jq 'select(.result == "denied")'
# just the denies

The audit log lives at ~/.opena2a/aim-core/audit.jsonl. Append-only. Rotation at 50 MB, last 5 generations kept. Forward to Splunk or Sentinel via the standard tail-and-forward pattern.

Encryption at rest is filesystem-level. The JSONL stores unencrypted so grep and jq work without ceremony. For compliance use cases, encrypt ~/.opena2a/ with FileVault on macOS, LUKS on Linux, or BitLocker on Windows, or ship to a KMS-backed log aggregator.

Self-host or AIM Cloud

opena2a-cli works offline by default. The optional server path:

• AIM Cloud. Managed at aim.opena2a.org. opena2a login and you're done.
• Self-hosted AIM. Docker stack from agent-identity-management. REST API, dashboard, Postgres-backed audit log, OAuth, 9-factor real-time trust scoring with NanoMind, 5-step Fine-Grained Authorization pipeline. Run bash quickstart.sh to bring it up.

Local-only mode covers identity, audit, capability policies, and trust scoring. Server adds real-time enforcement, multi-machine fleet management, the dashboard, and MCP attestation. The CLI is the same in both modes. --server switches it.

Use cases

Guide	Time
Developer using AI coding tools	5 min
Security team assessing AI risk across a fleet	10 min
MCP server author shipping safely	15 min
CI/CD pipeline integration	20 min

Full index: docs/USE-CASES.md.

Contributing

Apache 2.0. PRs from outside the org welcome. CONTRIBUTING.md has the dev loop, the test conventions, and what to expect on a pull request opened from a fork.

git clone https://github.com/opena2a-org/opena2a.git
cd opena2a && npm install && npm run build && npm test

Security issues: info@opena2a.org (coordinated disclosure, response within 24 hours).

Links

• Website
• Documentation
• Demos
• AIM
• HackMyAgent
• Secretless
• Research

Part of the OpenA2A security platform.

License

Apache-2.0. See LICENSE.