OpenA2A: CLI · HackMyAgent · Secretless · AIM · Browser Guard · DVAA
Cryptographic identity, capability authorization, and audit trails for AI agents.
pip install "aim-sdk[rich]"
aim-sdk login # OAuth to aim.opena2a.org
aim-sdk login --url http://localhost:8080 # or to your self-hosted AIMThe [rich] extra is optional and formats the output shown below; plain pip install aim-sdk works and prints the same fields in a panel. Then register an agent, in a Python session, with the capability it holds. What secure() prints, trimmed (full output):
from aim_sdk import secure
agent = secure("my-first-agent", capabilities=["db:read"]) ○ Agent Type: using default 'ai_agent'
[OK] Agent registered: my-first-agent
...
Status: ○ pending Trust: 59%
Capabilities: db:read
aim-sdk login prints a code you approve on your dashboard's /device page. secure() generates an Ed25519 keypair and stores credentials at ~/.aim/.
The agent starts pending until an administrator verifies it under Agents in the dashboard. On a new organization, which starts in monitoring mode, a pending agent's call runs and raises an Unverified Agent Action (Monitoring Mode) alert. On a strict-mode organization every call is refused with Agent not verified - all actions denied until then.
Once it is verified, protect a function with that capability and call it:
customers = {42: {"name": "Ada Lovelace", "plan": "team"}}
@agent.perform_action(capability="db:read")
def get_customer(customer_id):
return customers[customer_id]
get_customer(42)@perform_action signs each call, has the server check it against the agent's granted capabilities and the organization's security policies, and logs the outcome.
The refusal below needs strict mode (dashboard: Security, then Policies, Global Enforcement Mode: Strict); in the default monitoring mode, db:write runs and deletes the record.
Now call something the agent was not granted. my-first-agent holds db:read only:
@agent.perform_action(capability="db:write")
def delete_customer(customer_id):
del customers[customer_id]
delete_customer(42)AIM refuses it before the function body runs. What the call prints, trimmed (full output):
Capability 'db:write' pending admin approval (strict mode)
aim_sdk.exceptions.ActionDeniedError: AIM denied 'db:write': Capability violation blocked by security policy 'Capability Violation Detection': Agent does not have permission for capability 'db:write' (allowed: [db:read]). The action was blocked and not executed. AIM denies an action after applying your organization's enforcement mode (currently strict), so a denial blocks in every mode -- monitoring mode governs verifications AIM could not answer, not ones it refused. To permit this capability, grant it to this agent in the AIM dashboard under Agents. If the agent should not be denied at all, check its status there: an agent marked compromised, suspended or unverified is refused regardless of its capabilities.
The decorator files a request for db:write, and the agent's audit log records the denial with the same reason. On a stack started from the quickstart defaults, the reason names the built-in default_policy instead of 'Capability Violation Detection'.
The SDK built from this repository printed the registration capture, and the release on PyPI printed the refusal; the release on PyPI prints ✓ where this repository's build prints [OK], and adds ✓ Registered db:write (medium) after the refusal's first line.
The trust score is calculated at registration and recalculated when a manager verifies, suspends or reactivates the agent, grants or revokes a capability, or calls POST /api/v1/agents/:id/trust-score/recalculate.
A verification request (POST /api/v1/verifications) does not recalculate the score. A request for a capability the agent was granted leaves the score unchanged. When a verified agent that holds at least one granted capability, and is not marked compromised, requests a capability outside its grants, the score drops by a fixed 0.10 if the request is blocked and 0.05 if it is let through, never below 0.
The same one-line shape works in Java; TypeScript has no secure() call (local mode).
- Protect an agent's calls in Python: Quick start.
- Protect them in Java: Java quick start.
- Check capabilities and keep an audit log with no server: local mode in TypeScript.
- Audit a codebase: the opena2a CLI's commands.
- Register an agent from an app or the terminal: Register an agent.
- Track what an agent does: Audit agent actions.
- Restrict what an agent can do: Enforce capabilities.
- Add identity to your agent framework: Embed in an app.
- Govern many agents: Fleet governance.
- Gate privileged actions, attest MCP servers and forward audit logs to Splunk: Server features.
- Run AIM on your own machines: Install AIM (self-hosted).
| Mode | When | Includes |
|---|---|---|
| AIM Cloud | Managed | Hosted at aim.opena2a.org/get-started. Python and Java SDKs work out of the box. |
| Self-hosted | Your infrastructure | All AIM Cloud features. PostgreSQL audit, REST API, dashboard, OAuth, 5-step FGA, 9-factor trust score, MCP attestation, PAM, SIEM adapters. |
| Local-only | One machine, no server | TypeScript SDK + opena2a CLI. Ed25519 keypair, audit.jsonl, YAML capability policies, 8-factor local trust score. Local mode is in the TypeScript SDK only. |
Local only mode keeps its own event format in ~/.opena2a/aim-core/audit.jsonl, separate from the server's audit log.
| SDK | Install | Mode | API |
|---|---|---|---|
| Python | pip install aim-sdk |
Server | secure("name") + @perform_action |
| Java | cd sdk/java && mvn install (from source) |
Server | AIMClient.secure("name") + @SecureAction |
| TypeScript | npm install @opena2a/aim-core |
Local | new AIMCore({ agentName }) |
Each SDK's README: Python, Java, TypeScript; examples for all three are in examples/. The SDKs send requests only to the AIM server you signed in to; the causal-denial telemetry the Python and TypeScript SDK READMEs describe is opt-in and off until you configure it; the Java SDK has none.
AIMClient agent = AIMClient.secure("my-first-agent");
@SecureAction(capability = "db:read", resource = "users_table")
public User getCustomer(String customerId) {
return userRepository.findById(customerId);
}AspectJ wraps each @SecureAction invocation with the same Ed25519 signing and audit trail.
curl -sSLO https://raw.githubusercontent.com/opena2a-org/agent-identity-management/main/scripts/quickstart.sh
bash quickstart.shIt needs Docker running, openssl and curl, and writes the compose file and a .env of generated secrets to ./aim. Brings up aim-server, aim-dashboard, PostgreSQL, and Redis. Dashboard at localhost:3000, API at localhost:8080. Login credentials print at the end of the run.
The script runs from main and starts the aim-server and aim-dashboard images at their latest tags; nothing on this path is pinned or verified, so read the script and the compose file first.
Image tags, building from source, observability and the first administrator on other setups: docs/DEPLOYMENT.md. Production on Azure, GCP or AWS: infrastructure/DEPLOYMENT.md.
- See it work: the audit log behind the two calls above, where to grant
db:write, and the Quick start's notes in full. - Server features, Deployment, Verifying the
@opena2a/aim-corepackage, Use cases, Demos and the A/B recording. - opena2a CLI commands: harden configs and monitor runtime events, with no server.
- SDK quickstart tutorial, MCP registration, the documentation site, Research.
- Roadmap
- Contributing: the dev loop and pull requests. Report security issues to
info@opena2a.org; SECURITY.md says what to expect.
Apache-2.0. See LICENSE.