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 review

  OpenA2A Security Review

  Findings
  -----------------------------------------------
  Credential scan        3 hardcoded keys
  Shadow AI              2 agents, 4 MCP servers
  Config integrity       unsigned
  Governance             no SOUL.md
  -----------------------------------------------
  Security Score   30 / 100  ->  85 by running opena2a protect

  Run: opena2a protect    (fix all findings)

Install

npm

npx opena2a-cli review          # 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 release publishes via npm Trusted Publishing with SLSA v1 provenance. No long-lived NPM_TOKEN. GitHub Actions exchanges its OIDC token with npm at publish time.

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.

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

Built-in help

opena2a ?                              # recommendations for THIS project
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

Protect

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

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

Full index: docs/USE-CASES.md.

Contributing

Apache 2.0. PRs from outside the org welcome. CONTRIBUTING.md has the dev loop, test conventions, and pre-push review gates.

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

Security issues: [email protected] (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.