opena2a identity
Agent identity management. Adapter for @opena2a/aim-core.
Usage
opena2a identity <subcommand> [options]Subcommands
Identity and Keys
| Subcommand | Description |
|---|---|
list | Display the local agent identity and its metadata (agent ID, name, public key, creation date, data directory). |
show | Alias for list. |
create --name <name> | Create a new Ed25519 agent identity with the specified name. If an identity already exists in the data directory, displays the existing identity instead. |
sign --data <string> | Sign a string with the agent private key. Returns a base64-encoded Ed25519 signature and the corresponding public key. |
sign --file <path> | Sign the contents of a file with the agent private key. |
verify --data <d> --signature <sig> --public-key <key> | Verify a base64-encoded signature against the provided data and public key. Exits 0 if valid, 1 if invalid. |
Trust and Audit
| Subcommand | Description |
|---|---|
trust | Calculate and display the composite trust score (0-100) with a factor-by-factor breakdown including progress bars. With --verbose, shows improvement suggestions for factors at 0%. Auto-syncs trust hints from attached tools. |
audit [--limit N] | List recent identity audit events in chronological order (default: last 10). Each entry shows timestamp, action, target, and result (allowed/denied/error). |
log --action <a> [--target <t>] [--result <r>] | Manually log a security audit event. Result defaults to "allowed". Valid results: allowed, denied, error. |
Policy
| Subcommand | Description |
|---|---|
policy | Display the current capability policy: default action (allow/deny) and all rules. |
policy --file <path> | Load a capability policy from a YAML or JSON file. Supports .yaml, .yml, and .json formats. The policy defines allow/deny rules per capability with optional plugin scoping. |
check <capability> [--plugin <name>] | Check whether a specific capability is allowed or denied by the current policy. Optionally scope the check to a specific plugin. Exits 0 if allowed, 1 if denied. |
Cross-Tool Integration
| Subcommand | Description |
|---|---|
attach [--tools <list>] | Wire security tools to the agent identity for unified audit and trust scoring. Detects and connects Secretless, ConfigGuard, ARP, HMA, and Shield. Imports existing events and writes an agent manifest to .opena2a/agent.yaml. |
attach --all | Enable all detected tools. |
detach | Remove cross-tool wiring. The identity, audit log, and tool configurations are preserved; only the manifest linking them is removed. |
sync | Re-sync audit events from all attached tools. Imports new events since the last sync, refreshes trust hints, and updates the trust score. |
Description
Manages agent identities through the @opena2a/aim-core adapter. Each identity is an Ed25519 keypair stored locally in ~/.opena2a/aim-core/. Identities can be registered with the OpenA2A Registry for trust verification.
The trust subcommand calculates a composite trust score from factors such as credential hygiene, configuration integrity, and scan history. When tools are attached via attach, trust scores incorporate real security state from Secretless, ConfigGuard, ARP, HMA, and Shield.
The policy and check subcommands implement capability-based access control. Policies define allow/deny rules per capability (e.g., db:read, net:*) with optional plugin-level scoping.
The sign and verify subcommands enable Ed25519 cryptographic operations using the agent keypair, useful for signing configurations, messages, or files and verifying signatures from other agents.
Requires @opena2a/aim-core to be installed. Install with npm install @opena2a/aim-core.
Flags
| Flag | Description |
|---|---|
--name <name> | Agent name (used with create and attach). |
--limit <N> | Number of audit entries to display (default: 10). |
--action <action> | Action name for the log subcommand (e.g., db:read, net:connect). |
--target <target> | Target resource for the log subcommand. |
--result <result> | Event result for the log subcommand: allowed, denied, or error (default: allowed). |
--file <path> | File path for policy load or sign --file. |
--data <string> | Data string for sign and verify. |
--signature <base64> | Base64-encoded signature for verify. |
--public-key <base64> | Base64-encoded public key for verify. |
--tools <list> | Comma-separated tool list for attach (e.g., secretless,hma,guard). |
--all | Enable all detected tools (used with attach). |
--plugin <name> | Plugin name for log and check subcommands. |
--dir <path> | Target directory (default: current directory). |
--format <text|json> | Output format. |
--ci | CI mode with deterministic output. |
--verbose | Show detailed output including improvement suggestions. |
Examples
# Show local identity
opena2a identity list# Create a new identity
opena2a identity create --name my-agent# View trust score with factor breakdown
opena2a identity trust# View trust score with improvement suggestions
opena2a identity trust --verbose# Audit last 20 identity events
opena2a identity audit --limit 20# Log a security event
opena2a identity log --action db:read --target customers --result allowed# Load a capability policy from YAML
opena2a identity policy --file policy.yaml# Check if a capability is allowed
opena2a identity check db:read# Check capability scoped to a plugin
opena2a identity check net:connect --plugin untrusted-plugin# Sign a string
opena2a identity sign --data "message to sign"# Sign a file
opena2a identity sign --file ./config.json# Verify a signature
opena2a identity verify --data "message" --signature <base64> --public-key <base64># Attach all tools to identity
opena2a identity attach --all# Attach specific tools
opena2a identity attach --tools secretless,hma,guard# Detach identity from tools
opena2a identity detach# Sync events from attached tools
opena2a identity syncSDK Integration
The identity management capabilities are also available programmatically through the AIM SDKs: