opena2a shield
Unified security orchestration for AI coding assistants. Event log, policy evaluation, runtime monitoring, session identification, integrity checks, and LLM-powered analysis.
Usage
opena2a shield <subcommand> [options]Quick Start
Capabilities
Shield's policy has three modes. opena2a shield init writes adaptive, the default. The mode is the mode field in ~/.opena2a/shield/policy.yaml, and opena2a shield policy shows it. In adaptive and monitor modes, opena2a shield evaluate reports a command the policy denies as MONITORED and exits 0. In enforce mode it reports the command as blocked and exits 1.
| 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 |
| Event log | Each event records the SHA-256 hash of the event before it; the hashes use no key | Active |
| Policy evaluation | Allow/deny rules for processes, credentials, network, filesystem, MCP servers | Active |
| Session identification | Names the current AI assistant from environment variables (claude-code, cursor, copilot, aider) | Active |
| Config integrity | Records a SHA-256 hash of each tracked config file and reports files that changed or went missing | 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 |
| 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 with --shell-hook, an event in the Shield event log (contrast with read-only opena2a init) |
status | Tool availability, policy mode, shell integration, integrity state |
log | Query the Shield 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 | Name the AI coding assistant from environment variables (claude-code, cursor, copilot, aider, or unknown) |
recover | Exit lockdown mode, with optional verification. No Shield check currently puts the system into lockdown. |
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 | Show per-agent behavioral baselines. No Shield command in opena2a-cli 0.10.13 records one. |
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, when run with --shell-hook installs shell hooks, and writes an event to the Shield event log. Unlike the read-only opena2a init assessment,shield init actively configures security infrastructure in your project. Without --shell-hook, step 7 prints Skipped (opt-in: use --shell-hook to install) and init leaves your shell startup files unchanged. With it, init adds the hook to ~/.zshrc or ~/.bashrc, whichever matches your SHELL.
shield log
Query the Shield event log with filters. Each event records the SHA-256 hash of the event before it.
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's previous-hash field matches the recorded hash of the event before it |
| Process | Node.js binary exists and appears legitimate |
| Artifact signatures | Each tracked Shield file matches its recorded SHA-256 hash |
shield monitor
Import ARP (Agent Runtime Protection) events into the Shield event log and display runtime protection stats. Events from HackMyAgent's ARP module are translated into Shield's unified event format.
shield session
Name the AI coding assistant the current shell runs under, from environment variables. opena2a-cli 0.10.13 reports claude-code when CLAUDE_CODE is set or TERM_PROGRAM is claude, cursor when CURSOR is set, copilot when VSCODE_PID is set, and aider when TERM_PROGRAM is aider. It has no rule for Devin Desktop (formerly Windsurf) or Continue, and a shell that matches none of these prints Agent: unknown. Claude Code sets CLAUDECODE, which this command does not read, so a Claude Code session prints Agent: unknown unless CLAUDE_CODE is set or TERM_PROGRAM is claude.
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
Show per-agent behavioral baselines. The command only reads them, from ~/.opena2a/shield/baselines/. No Shield command in opena2a-cli 0.10.13 records a baseline, so after shield evaluate has logged events, opena2a shield baseline still prints No baselines found. and exits 0. With --agent <name> it prints an empty baseline for that agent (phase learn, 0 actions, 0 sessions) and does not save it.
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. They need an LLM backend. opena2a-cli 0.10.13 uses the claude CLI when it is on your PATH and the CLAUDECODE environment variable is not set (a Claude Code session sets it). Otherwise it uses an Anthropic API key in ANTHROPIC_API_KEY, and only after opena2a config llm on, with one exception: it reads that setting through its @opena2a/shared dependency and, when that package fails to load, uses the key without the setting. With neither backend, the three subcommands print LLM intelligence is not available. and exit 1, and shield report --analyze prints the report with a line saying the analysis is unavailable. Shield calls an LLM only when you run one of these subcommands or shield report --analyze.
Options
| Flag | Type | Description |
|---|---|---|
--dir <path> | string | Target directory. Defaults to current working directory. |
--agent <name> | string | Agent name for log, suggest, explain, triage, baseline. |
--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. Matches that one level, so high does not include 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. |
--shell-hook | boolean | Install the shell hook in ~/.zshrc or ~/.bashrc (shield init only). |
--verbose | boolean | Show additional details (e.g., raw session signals). |
--format <type> | text | json | Output format. Default: text. |
Event Log Format
Shield keeps its event log at ~/.opena2a/shield/events.jsonl, one JSON event per line. Each event records the SHA-256 hash of the event before it, and the first event records a fixed public value in its place. The hashes use no key, so any program that can write the file, including an AI coding assistant running as the same user, can change events and recompute the hashes after them.
What opena2a shield log --count 3 prints (captured from opena2a-cli 0.10.13, 2026-10-06, on a scratch HOME with the default Shield policy, after opena2a shield evaluate checked aws s3 ls, kubectl get secrets and gcloud auth list):
Exit Codes
| Code | Meaning |
|---|---|
0 | Success (healthy, allowed, recovered). selfcheck also exits 0 when its overall status is degraded. |
1 | Failure (compromised, lockdown, blocked, no policy, unknown subcommand) |