opena2a shield
Unified security orchestration for AI coding assistants. Tamper-evident event log, policy evaluation, runtime monitoring, session identification, integrity verification, and LLM-powered analysis.
Usage
opena2a shield <subcommand> [options]Quick Start
Capabilities
Shield operates in three modes: monitor (default) logs and surfaces events,enforce blocks denied commands via shell hooks, and baseline learning observes agent behavior across sessions to suggest policy rules when behavior stabilizes.
| Capability | Description | Status |
|---|---|---|
| Credential scanning | Detects hardcoded API keys (Anthropic, OpenAI, AWS, Google, GitHub) | Active |
| Scope drift detection | Finds keys that silently access unintended services (DRIFT-001, DRIFT-002) | Active |
| Tamper-evident event log | SHA-256 hash-chained log -- any modification breaks the chain | Active |
| Policy evaluation | Allow/deny rules for processes, credentials, network, filesystem, MCP servers | Active |
| Session identification | Detects which AI assistant is running via environment and process signals | Active |
| Config integrity | Signs config files and detects unauthorized modifications | Active |
| ARP bridge | Imports runtime protection events from HackMyAgent ARP | Active |
| Posture scoring | 0-100 security score based on active tools, policy, hooks, credentials | Active |
| LLM intelligence | Policy suggestions, anomaly explanations, incident triage | Opt-in |
| Integrity selfcheck | Verifies policy, shell hooks, event chain, process, artifact signatures | Active |
| Lockdown mode | Enters lockdown on integrity failure; requires explicit recovery | Active |
| Adaptive baselines | Learns per-agent behavior, tracks stability across sessions, suggests policies | Active |
| Enforcement mode | Shell hooks check policy and block denied commands in enforce mode | Active |
| HTML posture report | Interactive dark-theme report with severity chart, filters, agent activity | Active |
Subcommands
| Subcommand | Description |
|---|---|
init | 11-step security setup: environment scan, policy generation, shell hooks, genesis event (contrast with read-only opena2a init) |
status | Tool availability, policy mode, shell integration, integrity state |
log | Query the tamper-evident event log with filters (severity, source, agent, time) |
selfcheck | Run integrity checks: policy hash, shell hook, event chain, process binary, artifact signatures |
policy | Show loaded security policy (mode, rule counts, agent overrides) |
evaluate | Evaluate an action against the loaded policy (ALLOWED, BLOCKED, MONITORED) |
monitor | Import ARP runtime events into Shield log and display runtime stats |
report | Generate a security posture report with severity breakdown and agent activity |
session | Detect current AI coding assistant (Claude Code, Cursor, Copilot, Windsurf) |
recover | Exit lockdown mode after integrity failures, with optional verification |
suggest | LLM-powered policy suggestions based on observed agent behavior |
explain | LLM-powered anomaly explanations with risk factors and recommended actions |
triage | LLM-powered incident classification: false-positive, suspicious, confirmed-threat |
baseline | Manage per-agent behavioral baselines with stability tracking and phase transitions |
Subcommand Details
shield init
11-step security setup that detects project type, scans for credentials, discovers AI assistants, MCP servers, and OAuth sessions, generates a YAML policy file, installs shell hooks, and writes a genesis event to the tamper-evident log. Unlike the read-only opena2a init assessment,shield init actively configures security infrastructure in your project.
shield log
Query the tamper-evident event log with filters. Each event is SHA-256 hash-chained to the previous.
shield selfcheck
Runs five integrity checks and returns an overall status: healthy, degraded, or compromised.
| Check | Verifies |
|---|---|
| Policy | Policy file hash matches recorded value |
| Shell hook | Shell hook content matches expected template |
| Event chain | Each event hash-chains to the previous |
| Process | Node.js binary exists and appears legitimate |
| Artifact signatures | All signed artifacts match their recorded hashes |
shield monitor
Import ARP (Agent Runtime Protection) events into Shield's hash-chained log and display runtime protection stats. Events from HackMyAgent's ARP module are translated into Shield's unified event format.
shield session
Detect the current AI coding assistant session. Identifies Claude Code, Cursor, GitHub Copilot, Windsurf, Aider, and Continue via environment variables, process signals, and TTY detection.
shield report
Generate a security posture report from event data. Includes severity breakdown, agent activity, policy violations, top actions, and optional LLM-powered narrative. Supports interactive HTML output.
shield baseline
Manage per-agent behavioral baselines. Baselines track observed actions across sessions and compute stability scores. Phases: learning (collecting) → stabilizing (fewer new behaviors) → stable (ready for policy generation).
Enforcement Mode
When shield init installs shell hooks and the policy mode is set to enforce, each command is evaluated against the loaded policy before execution. Denied commands are blocked with exit code 1.
LLM Intelligence (suggest, explain, triage)
Three LLM-powered subcommands provide AI analysis of security events. Requires an LLM backend (enable with opena2a config llm on). Zero network calls by default.
Options
| Flag | Type | Description |
|---|---|---|
--dir <path> | string | Target directory. Defaults to current working directory. |
--agent <name> | string | Agent name filter for log, suggest, explain, triage. |
--count <n> | number | Event count for log and explain. Default: 20 (log), 1 (explain). |
--since <timespec> | string | Time filter: 7d, 1w, 1m, or ISO 8601 timestamp. |
--severity <level> | string | Severity filter: info, low, medium, high, critical. |
--source <source> | string | Event source filter (e.g., arp, secretless, shield). |
--category <cat> | string | Event category filter. |
--verify | boolean | Verify integrity before exiting lockdown (recover). |
--analyze | boolean | Include LLM-powered narrative in reports. |
--report <path> | string | Write interactive HTML posture report to file. |
--verbose | boolean | Show additional details (e.g., raw session signals). |
--format <type> | text | json | Output format. Default: text. |
Event Log Format
Shield maintains a tamper-evident event log at ~/.opena2a/shield/events.jsonl. Each event is SHA-256 hash-chained to the previous, starting from a genesis hash. Any modification to a past event breaks the chain and is detected by selfcheck.
Exit Codes
| Code | Meaning |
|---|---|
0 | Success (healthy, allowed, recovered) |
1 | Failure (compromised, lockdown, blocked, no policy, unknown subcommand) |