hackmyagent 0.8.0 → 0.9.0

package/README.md

@@ -1,94 +1,59 @@
-> **[OpenA2A](https://github.com/opena2a-org/opena2a)**: [Secretless](https://github.com/opena2a-org/secretless-ai) · [ABG](https://github.com/opena2a-org/AI-BrowserGuard) · [AIM](https://github.com/opena2a-org/agent-identity-management) · [OASB](https://github.com/opena2a-org/oasb) · [ARP](https://github.com/opena2a-org/arp) · [DVAA](https://github.com/opena2a-org/damn-vulnerable-ai-agent)
+> **[OpenA2A](https://github.com/opena2a-org)**: [CLI](https://github.com/opena2a-org/opena2a) · [Secretless](https://github.com/opena2a-org/secretless-ai) · [AIM](https://github.com/opena2a-org/agent-identity-management) · [Browser Guard](https://github.com/opena2a-org/AI-BrowserGuard) · [DVAA](https://github.com/opena2a-org/damn-vulnerable-ai-agent) · [Registry](https://registry.opena2a.org)
 
 # HackMyAgent
 
 [![npm version](https://img.shields.io/npm/v/hackmyagent.svg)](https://www.npmjs.com/package/hackmyagent)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![Tests](https://img.shields.io/badge/tests-611%20passing-brightgreen)](https://github.com/opena2a-org/hackmyagent)
+[![Tests](https://img.shields.io/badge/tests-765%20passing-brightgreen)](https://github.com/opena2a-org/hackmyagent)
 
 **Find it. Break it. Fix it.**
 
-The hacker's toolkit for AI agents. 147 security checks, 55 attack payloads, auto-fix with rollback, and OASB benchmark compliance. Scans Claude Code, Cursor, VS Code, and any MCP server setup for credential leaks, misconfigurations, prompt injection vectors, supply chain risks, and more.
+AI agents execute arbitrary code with your permissions. HackMyAgent finds what can go wrong before an attacker does.
 
-[Website](https://hackmyagent.com) | [Security Checks Reference](docs/SECURITY_CHECKS.md)
+Security scanner and red-team toolkit for AI agents. 147 security checks across 30 categories, 55 adversarial attack payloads, auto-fix with rollback, and OASB-1 compliance benchmarking -- all in a single package.
 
-<p align="center">
-  <img src="docs/hackmyagent-demo.gif" alt="HackMyAgent scanning an AI agent project" width="700" />
-</p>
+Scans Claude Code, Cursor, VS Code, and any MCP server setup.
+
+[Website](https://hackmyagent.com) | [Security Checks Reference](docs/SECURITY_CHECKS.md) | [OpenA2A CLI](https://github.com/opena2a-org/opena2a)
 
 ---
 
 ## Quick Start
 
 ```bash
-npx hackmyagent secure              # scan current directory (147 checks)
-npx hackmyagent secure --fix        # auto-fix what it finds
-npx hackmyagent fix-all --with-aim  # add agent identity + audit logging
+npx hackmyagent secure                # 147-check security scan
+npx hackmyagent secure --fix          # auto-fix issues (backups created automatically)
+npx hackmyagent attack --local        # red-team with 55 adversarial payloads
+npx hackmyagent secure -b oasb-1      # OASB-1 compliance benchmark
 ```
 
-No config files required. Works out of the box.
+No config files. No setup. Works out of the box on any AI agent project.
 
 ---
 
-## Usage via OpenA2A CLI
-
-HackMyAgent is available as a first-class adapter in the [OpenA2A CLI](https://github.com/opena2a-org/opena2a). If you have the CLI installed, you can invoke scanning, auto-fix, and attack capabilities directly:
-
-```bash
-opena2a scan                              # run HackMyAgent security scan on current directory
-opena2a scan --fix                        # scan and auto-fix issues
-opena2a scan --attack http://localhost:3000  # red-team a live endpoint with adversarial payloads
-```
-
-The `opena2a scan` adapter delegates to `hackmyagent secure` under the hood, supporting the same checks, output formats, and exit codes documented below.
+## What It Scans
 
-### Scope Drift Detection
+| Platform | What HackMyAgent detects |
+|----------|--------------------------|
+| **Claude Code** | CLAUDE.md misconfigurations, skill permissions, MCP server exposure |
+| **Cursor** | .cursor/ rules, MCP server configs, overly permissive settings |
+| **VS Code** | .vscode/mcp.json configurations, extension risks |
+| **Any MCP setup** | Transport security, tool boundaries, auth weaknesses |
 
-HackMyAgent includes credential scope drift detectors exposed through the `opena2a protect` command. These detect when AI agent credentials have permissions beyond their declared scope:
-
-| Detector | ID | What it detects |
-|----------|----|-----------------|
-| Google / Gemini | DRIFT-001 | OAuth scopes or API key permissions exceeding declared agent capabilities |
-| AWS / Bedrock | DRIFT-002 | IAM policies granting broader access than the agent's capability manifest |
-
-Preview drift findings without applying changes:
-
-```bash
-opena2a protect --dry-run
-```
-
----
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Usage via OpenA2A CLI](#usage-via-opena2a-cli)
-- [Commands](#commands)
-  - [secure](#hackmyagent-secure) — local agent hardening (147 checks)
-  - [fix-all](#hackmyagent-fix-all) — run all OpenA2A security plugins
-  - [check](#hackmyagent-check) — verify a skill before installing
-  - [scan](#hackmyagent-scan) — scan external infrastructure
-  - [attack](#hackmyagent-attack) — red team with adversarial payloads
-  - [secure --benchmark](#hackmyagent-secure---benchmark) — OASB-1 compliance benchmark
-  - [secure-openclaw](#hackmyagent-secure-openclaw) — OpenClaw-specific scanning
-  - [rollback](#hackmyagent-rollback) — undo auto-fix changes
-- [Plugin Architecture](#plugin-architecture)
-- [CI/CD Integration](#cicd-integration)
-- [Exit Codes](#exit-codes)
-- [Contributing](#contributing)
+All platforms are scanned automatically — no flags needed.
 
 ---
 
 ## Installation
 
 ```bash
-# Run directly (no install needed)
+# Run directly (no install)
 npx hackmyagent secure
 
 # Install globally
 npm install -g hackmyagent
 
-# Add to project devDependencies
+# Add to devDependencies
 npm install --save-dev hackmyagent
 ```
 
@@ -100,17 +65,16 @@ npm install --save-dev hackmyagent
 
 ### `hackmyagent secure`
 
-Scan and harden your local agent setup. 147 checks across 30 categories with auto-remediation.
+Run 147 security checks across 30 categories. The primary command most users need.
 
 ```bash
-hackmyagent secure                            # basic scan
+hackmyagent secure                            # scan current directory
 hackmyagent secure ./my-project               # scan specific directory
 hackmyagent secure --fix                      # auto-fix issues
 hackmyagent secure --fix --dry-run            # preview fixes before applying
 hackmyagent secure --ignore CRED-001,GIT-002  # skip specific checks
 hackmyagent secure --json                     # JSON output for CI/CD
 hackmyagent secure --verbose                  # show all checks including passed
-hackmyagent secure --no-color                 # disable colored output
 ```
 
 <details>
@@ -154,8 +118,6 @@ hackmyagent secure --no-color                 # disable colored output
 <details>
 <summary>Auto-fix capabilities</summary>
 
-**General (`hackmyagent secure --fix`):**
-
 | Check | Issue | Auto-fix |
 |-------|-------|----------|
 | CRED-001 | Exposed API keys | Replace with env var reference |
@@ -164,106 +126,32 @@ hackmyagent secure --no-color                 # disable colored output
 | PERM-001 | Overly permissive files | Set restrictive permissions |
 | MCP-001 | Root filesystem access | Scope to project directory |
 | NET-001 | Bound to 0.0.0.0 | Bind to 127.0.0.1 |
-
-**OpenClaw (`hackmyagent secure-openclaw --fix`):**
-
-| Check | Issue | Auto-fix |
-|-------|-------|----------|
-| GATEWAY-001 | Bound to 0.0.0.0 | Bind to 127.0.0.1 |
+| GATEWAY-001 | Gateway bound to 0.0.0.0 | Bind to 127.0.0.1 |
 | GATEWAY-003 | Plaintext token | Replace with `${OPENCLAW_AUTH_TOKEN}` |
 | GATEWAY-004 | Approvals disabled | Enable approvals |
 | GATEWAY-005 | Sandbox disabled | Enable sandbox |
 
-Use `--dry-run` first to preview changes. Backups are created automatically in `.hackmyagent-backup/`.
+Use `--dry-run` to preview changes. Backups are created in `.hackmyagent-backup/`.
 
 </details>
 
 ---
 
-### `hackmyagent fix-all`
-
-Run all OpenA2A security plugins in sequence: scan, fix, report.
-
-```bash
-hackmyagent fix-all                     # scan and fix current directory
-hackmyagent fix-all ./my-agent          # target specific directory
-hackmyagent fix-all --dry-run           # preview without applying
-hackmyagent fix-all --scan-only         # scan only, no fixes
-hackmyagent fix-all --json              # JSON output for CI
-hackmyagent fix-all --with-aim          # enable AIM identity + audit logging
-hackmyagent fix-all -v                  # verbose output
-```
-
-**Plugin execution order:**
-
-| # | Plugin | What it does |
-|---|--------|--------------|
-| 1 | **SkillGuard** | Hash pinning, tamper detection, dangerous pattern scanning (reverse shells, exfil, prompt injection) |
-| 2 | **SignCrypt** | Ed25519 signing of SKILL.md and HEARTBEAT.md, SHA-256 hash pinning, signature verification |
-| 3 | **CredVault** | Credential detection (10 patterns), env var replacement, AES-256-GCM encrypted store |
-
-**`--with-aim` adds:**
-- Ed25519 identity generation for the agent
-- Cryptographic audit log at `.opena2a/aim/audit.jsonl`
-- Capability policy enforcement via `policy.yaml`
-- 8-factor trust scoring
-
----
-
-### `hackmyagent check`
-
-Verify a skill before installing it.
-
-```bash
-hackmyagent check @publisher/skill-name
-hackmyagent check @publisher/skill --json
-hackmyagent check @publisher/skill --offline    # skip DNS verification
-```
-
-Checks: publisher identity (DNS TXT), permissions requested, revocation status.
-
----
-
-### `hackmyagent scan`
-
-Scan external infrastructure for exposed AI agent endpoints.
-
-```bash
-hackmyagent scan example.com
-hackmyagent scan 192.168.1.100 -p 3000,8080
-hackmyagent scan example.com --json
-```
-
-Detects: exposed MCP SSE/tools endpoints, public configs, API keys in responses, debug interfaces.
-
-Scoring: A (90-100), B (80-89), C (70-79), D (60-69), F (<60).
-
-> Only scan systems you own or have written authorization to test.
-
----
-
 ### `hackmyagent attack`
 
-Red team your AI agent with 55 adversarial payloads across 5 categories.
+Red-team your AI agent with 55 adversarial payloads across 5 attack categories.
 
 ```bash
 hackmyagent attack --local                                    # local simulation
-hackmyagent attack --local --system-prompt "You are helpful"  # with custom prompt
+hackmyagent attack --local --system-prompt "You are helpful"  # with custom system prompt
 hackmyagent attack https://api.example.com/v1/chat            # test live endpoint
 hackmyagent attack --local --category prompt-injection         # single category
-hackmyagent attack --local --intensity aggressive              # full suite
+hackmyagent attack --local --intensity aggressive              # full payload suite
 hackmyagent attack --local -f sarif -o results.sarif           # SARIF output
 hackmyagent attack https://api.example.com --fail-on-vulnerable medium  # CI gate
-hackmyagent attack https://api.example.com --api-format anthropic       # Anthropic API
-hackmyagent attack https://api.example.com --model gpt-4o              # specify model
-hackmyagent attack https://api.example.com -H "Authorization: Bearer tk" # custom header
-hackmyagent attack --local --timeout 5000 --delay 500                   # timing controls
-hackmyagent attack --local --stop-on-success                            # stop at first hit
+hackmyagent attack https://api.example.com --api-format anthropic       # Anthropic API format
 ```
 
-<details>
-<summary>Attack categories and custom payloads</summary>
-
 | Category | Payloads | Description |
 |----------|----------|-------------|
 | `prompt-injection` | 12 | Manipulate agent behavior via injected instructions |
@@ -272,9 +160,14 @@ hackmyagent attack --local --stop-on-success                            # stop a
 | `capability-abuse` | 10 | Misuse agent tools for unintended actions |
 | `context-manipulation` | 10 | Poison agent context or memory |
 
-Intensity: `passive` (observation only), `active` (default), `aggressive` (full suite).
+Intensity levels: `passive` (observation only), `active` (default), `aggressive` (full suite).
+
+Output formats: `text`, `json`, `sarif` (GitHub Security tab), `html`.
+
+<details>
+<summary>Custom payloads</summary>
 
-**Custom payloads:** Create a JSON file and pass with `--payload-file custom.json`:
+Create a JSON file and pass with `--payload-file custom.json`:
 
 ```json
 {
@@ -297,26 +190,25 @@ Only `id` and `payload` are required.
 
 </details>
 
-Output formats: `text`, `json`, `sarif` (GitHub Security tab), `html`.
+> Only test systems you own or have written authorization to test.
 
 ---
 
-### `hackmyagent secure --benchmark`
+### `hackmyagent secure -b oasb-1`
 
-Run the [OASB-1](https://oasb.ai/oasb-1) (Open Agent Security Benchmark) — 46 controls across 10 categories.
+Run the [OASB-1](https://oasb.ai/oasb-1) (Open Agent Security Benchmark) — 46 controls across 10 categories with three maturity levels.
 
 ```bash
 hackmyagent secure -b oasb-1              # L1 baseline (26 controls)
 hackmyagent secure -b oasb-1 -l L2        # L2 standard (44 controls)
 hackmyagent secure -b oasb-1 -l L3        # L3 hardened (46 controls)
-hackmyagent secure -b oasb-1 -c "Input Security"     # filter to one category
-hackmyagent secure -b oasb-1 -v           # verbose (every control)
+hackmyagent secure -b oasb-1 -c "Input Security"     # filter by category
 hackmyagent secure -b oasb-1 -f html -o report.html  # HTML report
 hackmyagent secure -b oasb-1 --fail-below 70          # CI gate
 ```
 
 <details>
-<summary>OASB-1 categories and maturity levels</summary>
+<summary>OASB-1 categories</summary>
 
 | # | Category | Controls |
 |---|----------|----------|
@@ -341,143 +233,86 @@ Output formats: `text`, `json`, `sarif`, `html`, `asp` (Agent Security Profile).
 
 ---
 
-### `hackmyagent secure-openclaw`
+### `hackmyagent fix-all`
 
-47 specialized checks for OpenClaw/Moltbot installations.
+Run all security plugins in sequence: credential vault, file signing, skill guard. Applies fixes and generates a report.
 
 ```bash
-hackmyagent secure-openclaw                    # scan default location
-hackmyagent secure-openclaw ~/.moltbot         # specific directory
-hackmyagent secure-openclaw --fix              # auto-fix gateway configs
-hackmyagent secure-openclaw --fix --dry-run    # preview fixes
-hackmyagent secure-openclaw --json             # JSON output
+hackmyagent fix-all                     # scan and fix
+hackmyagent fix-all ./my-agent          # target specific directory
+hackmyagent fix-all --dry-run           # preview without modifying
+hackmyagent fix-all --scan-only         # scan only, no fixes
+hackmyagent fix-all --with-aim          # add agent identity + audit logging
+hackmyagent fix-all --json              # JSON output
 ```
 
-Detects: CVE-2026-25253, ClawHavoc IOCs, reverse shells, credential exfiltration, gateway misconfigs, disabled sandbox.
+**Plugins run in order:**
 
-See [SECURITY_CHECKS.md](docs/SECURITY_CHECKS.md#openclaw-security-checks) for full documentation.
+| Plugin | What it does |
+|--------|--------------|
+| **SkillGuard** | Hash pinning, tamper detection, dangerous pattern scanning (reverse shells, exfiltration, prompt injection) |
+| **SignCrypt** | Ed25519 signing of SKILL.md and HEARTBEAT.md, SHA-256 hash pinning, signature verification |
+| **CredVault** | Credential detection (10 patterns), env var replacement, AES-256-GCM encrypted store |
+
+**`--with-aim` adds:** Ed25519 agent identity, cryptographic audit log, capability policy enforcement, 8-factor trust scoring.
 
 ---
 
-### `hackmyagent rollback`
+### `hackmyagent check`
 
-Undo auto-fix changes. Backups are created automatically in `.hackmyagent-backup/`.
+Verify a skill's publisher identity and permissions before installing it.
 
 ```bash
-hackmyagent rollback                # rollback current directory
-hackmyagent rollback ./my-project   # rollback specific directory
+hackmyagent check @publisher/skill-name
+hackmyagent check @publisher/skill --json
+hackmyagent check @publisher/skill --offline    # skip DNS verification
 ```
 
----
-
-## Plugin Architecture
-
-HackMyAgent uses a modular plugin system. Each plugin implements `scan()` to detect issues and `fix()` to remediate them.
-
-### Built-in Plugins
+Checks: publisher identity (DNS TXT), permissions requested, revocation status.
 
-| Module | Description |
-|--------|-------------|
-| `src/plugins/core.ts` | Plugin interface, registry, shared types |
-| `src/plugins/credvault.ts` | Credential scanning (10 patterns), env var replacement, AES-256-GCM store |
-| `src/plugins/signcrypt.ts` | Ed25519 file signing, SHA-256 hash pinning, signature verification |
-| `src/plugins/skillguard.ts` | Permission pinning, tamper detection, dangerous pattern scanning |
+---
 
-### Writing a Plugin
+### `hackmyagent scan`
 
-```typescript
-import type {
-  OpenA2APlugin,
-  PluginMetadata,
-  PluginStatus,
-  Finding,
-  Remediation,
-  FixOptions,
-  PluginInitOptions,
-} from 'hackmyagent/plugins';
-
-export const metadata: PluginMetadata = {
-  packageName: '@my-org/my-plugin',
-  displayName: 'My Plugin',
-  description: 'Detects and fixes X',
-  version: '1.0.0',
-  findings: ['MY-001', 'MY-002'],
-  scoreImprovement: 10,
-};
+Scan external infrastructure for exposed AI agent endpoints.
 
-export class MyPlugin implements OpenA2APlugin {
-  readonly metadata = metadata;
+```bash
+hackmyagent scan example.com
+hackmyagent scan 192.168.1.100 -p 3000,8080
+hackmyagent scan example.com --json
+```
 
-  async init(options?: PluginInitOptions): Promise<void> {
-    // Access AIM Core for identity-aware audit logging:
-    // const aimCore = options?.aimCore;
-  }
+Detects: exposed MCP SSE/tools endpoints, public configs, API keys in responses, debug interfaces.
 
-  async scan(agentDir: string): Promise<Finding[]> {
-    // Scan the agent directory and return findings
-    return [
-      {
-        id: 'MY-001',
-        title: 'Insecure widget detected',
-        description: 'Widget at config.json line 12 uses plaintext.',
-        severity: 'high',        // critical | high | medium | low
-        filePath: 'config.json',
-        line: 12,
-        autoFixable: true,
-      },
-    ];
-  }
+Scoring: A (90-100), B (80-89), C (70-79), D (60-69), F (<60).
 
-  async fix(agentDir: string, options?: FixOptions): Promise<Remediation[]> {
-    if (options?.dryRun) {
-      // Return what would be fixed without modifying files
-      return [{ findingId: 'MY-001', description: 'Would encrypt widget', filesModified: ['config.json'], rollbackAvailable: false }];
-    }
+> Only scan systems you own or have written authorization to test.
 
-    // Apply fixes and return what was changed
-    return [{ findingId: 'MY-001', description: 'Encrypted widget', filesModified: ['config.json'], rollbackAvailable: false }];
-  }
+---
 
-  async status(): Promise<PluginStatus> {
-    return { name: metadata.displayName, version: metadata.version, active: true, findingsCount: 0 };
-  }
+### `hackmyagent rollback`
 
-  async uninstall(): Promise<void> {}
-}
+Undo auto-fix changes. Backups are created automatically by `secure --fix` and `fix-all`.
 
-export function createPlugin(): MyPlugin {
-  return new MyPlugin();
-}
+```bash
+hackmyagent rollback                # rollback current directory
+hackmyagent rollback ./my-project   # rollback specific directory
 ```
 
-Register the plugin in `@opena2a/plugin-core`:
-
-```typescript
-import { registerPlugin } from 'hackmyagent/plugins';
-import { createPlugin, metadata } from '@my-org/my-plugin';
-
-registerPlugin({
-  metadata,
-  create: createPlugin,
-});
-```
+---
 
-### Trust Score
+### `hackmyagent secure-openclaw`
 
-AIM Core provides an 8-factor weighted trust score (0.0 to 1.0) for each agent:
+47 specialized checks for OpenClaw/Moltbot installations.
 
-| Factor | Weight | What it measures |
-|--------|--------|------------------|
-| `identity` | 0.20 | Ed25519 keypair exists and is valid |
-| `capabilities` | 0.15 | Capabilities declared and pinned |
-| `secretsManaged` | 0.15 | No hardcoded credentials |
-| `auditLog` | 0.10 | Audit trail active |
-| `configSigned` | 0.10 | Configuration integrity verified |
-| `skillsVerified` | 0.10 | Skills cryptographically signed |
-| `networkControlled` | 0.10 | Network access restricted |
-| `heartbeatMonitored` | 0.10 | Heartbeat monitoring active |
+```bash
+hackmyagent secure-openclaw                    # scan default location
+hackmyagent secure-openclaw ~/.moltbot         # specific directory
+hackmyagent secure-openclaw --fix              # auto-fix gateway configs
+hackmyagent secure-openclaw --fix --dry-run    # preview fixes
+```
 
-Use `--with-aim` in `fix-all` to generate trust scores.
+Detects: CVE-2026-25253, ClawHavoc IOCs, reverse shells, credential exfiltration, gateway misconfigs, disabled sandbox.
 
 ---
 
@@ -496,7 +331,7 @@ jobs:
       - uses: actions/setup-node@v4
         with: { node-version: '20' }
       - run: npx hackmyagent secure --json > security-report.json
-      - run: npx hackmyagent fix-all --scan-only --json > plugin-report.json
+      - run: npx hackmyagent secure -b oasb-1 --fail-below 70
       - uses: actions/upload-artifact@v4
         with: { name: security-reports, path: '*.json' }
 ```
@@ -517,7 +352,7 @@ jobs:
 npx hackmyagent secure --ignore LOG-001,RATE-001
 ```
 
-### JSON Piping
+### JSON Output
 
 ```bash
 # Filter critical findings
@@ -531,22 +366,80 @@ hackmyagent secure --json | jq '[.findings[].id | split("-")[0]] | group_by(.) |
 
 ## Exit Codes
 
-| Code | Meaning | Commands |
-|------|---------|----------|
-| `0` | Clean — no critical/high issues | All commands |
-| `1` | Critical or high severity issues remain after scan/fix | `secure`, `fix-all`, `attack` |
-| `2` | Incomplete scan — one or more plugins failed to run | `fix-all` |
+| Code | Meaning |
+|------|---------|
+| `0` | Clean — no critical/high issues |
+| `1` | Critical or high severity issues found |
+| `2` | Incomplete scan — one or more plugins failed |
+
+---
+
+## What's Included
+
+HackMyAgent consolidates several OpenA2A security modules into a single package:
+
+| Module | Description | Previously |
+|--------|-------------|------------|
+| Security scanner | 147 checks across 30 categories | hackmyagent-core |
+| Attack simulation | 55 adversarial payloads, 5 categories | standalone |
+| CredVault plugin | Credential detection + AES-256-GCM vault | @opena2a/credvault |
+| SignCrypt plugin | Ed25519 signing + SHA-256 hash pinning | @opena2a/signcrypt |
+| SkillGuard plugin | Permission pinning + tamper detection | @opena2a/skillguard |
+| OASB benchmark | 46 controls, 3 maturity levels | @opena2a/oasb |
+| ARP integration | Agent Runtime Protection hooks | @opena2a/arp |
+| Semantic engine | Semantic analysis for finding deduplication | @opena2a/semantic-engine |
+
+### Subpath Exports
+
+For programmatic use, the package exposes subpath exports:
+
+```typescript
+import { HardeningScanner } from 'hackmyagent';           // Scanner engine
+import { registerPlugin } from 'hackmyagent/plugins';      // Plugin API
+import { SemanticEngine } from 'hackmyagent/semantic';      // Semantic analysis
+import { ARPMonitor } from 'hackmyagent/arp';               // Runtime protection
+import { OASBHarness } from 'hackmyagent/oasb';             // Benchmark harness
+```
 
 ---
 
-## Supported Platforms
+## Writing Plugins
+
+HackMyAgent supports custom security plugins. Each plugin implements `scan()` and `fix()` methods.
+
+```typescript
+import type { OpenA2APlugin, Finding, Remediation, FixOptions } from 'hackmyagent/plugins';
+
+export class MyPlugin implements OpenA2APlugin {
+  readonly metadata = {
+    packageName: '@my-org/my-plugin',
+    displayName: 'My Plugin',
+    description: 'Detects and fixes X',
+    version: '1.0.0',
+    findings: ['MY-001'],
+    scoreImprovement: 10,
+  };
+
+  async scan(agentDir: string): Promise<Finding[]> {
+    return [{
+      id: 'MY-001',
+      title: 'Insecure widget',
+      description: 'Widget uses plaintext.',
+      severity: 'high',
+      filePath: 'config.json',
+      line: 12,
+      autoFixable: true,
+    }];
+  }
+
+  async fix(agentDir: string, options?: FixOptions): Promise<Remediation[]> {
+    if (options?.dryRun) return [{ findingId: 'MY-001', description: 'Would encrypt widget', filesModified: ['config.json'], rollbackAvailable: false }];
+    return [{ findingId: 'MY-001', description: 'Encrypted widget', filesModified: ['config.json'], rollbackAvailable: false }];
+  }
+}
+```
 
-| Platform | What HackMyAgent scans |
-|----------|------------------------|
-| **Claude Code** | CLAUDE.md, skills, MCP server configs |
-| **Cursor** | .cursor/ rules, MCP configurations |
-| **VS Code** | .vscode/mcp.json configurations |
-| **Generic MCP** | Any MCP server setup |
+See the [full plugin API documentation](docs/PLUGIN_API.md) for details.
 
 ---
 
@@ -567,27 +460,7 @@ git clone https://github.com/opena2a-org/hackmyagent.git
 cd hackmyagent
 npm install
 npm run build
-npm test              # run 765 tests
-```
-
-### Project Structure
-
-```
-src/
-  cli.ts                    # CLI entry point (hackmyagent command)
-  index.ts                  # Main exports
-  hardening/                # Scanner engine (147 checks)
-  attack/                   # Red team attack simulation
-  checker/                  # Security check framework
-  scanner/                  # External scanner interface
-  semantic/                 # Semantic analysis engine
-  plugins/
-    core.ts                 # Plugin interface, registry, shared types
-    credvault.ts            # Credential scanner plugin
-    signcrypt.ts            # Signing and hash pinning plugin
-    skillguard.ts           # Permission and pattern scanner plugin
-  arp/                      # Agent Runtime Protection
-  oasb/                     # Open Agent Security Benchmark
+npm test              # 765 tests
 ```
 
 ---
@@ -602,8 +475,8 @@ Apache-2.0
 
 | Project | Description | Install |
 |---------|-------------|---------|
-| [**AIM**](https://github.com/opena2a-org/agent-identity-management) | Agent Identity Management -- identity and access control for AI agents | `pip install aim-sdk` |
-| [**OASB**](https://github.com/opena2a-org/oasb) | Open Agent Security Benchmark -- 222 attack scenarios | Included in `hackmyagent` |
-| [**ARP**](https://github.com/opena2a-org/arp) | Agent Runtime Protection -- process, network, filesystem monitoring | Included in `hackmyagent` |
+| [**OpenA2A CLI**](https://github.com/opena2a-org/opena2a) | Unified security CLI -- scan, protect, guard, runtime, shield | `npx opena2a` |
 | [**Secretless AI**](https://github.com/opena2a-org/secretless-ai) | Keep credentials out of AI context windows | `npx secretless-ai init` |
-| [**DVAA**](https://github.com/opena2a-org/damn-vulnerable-ai-agent) | Damn Vulnerable AI Agent -- security training and red-teaming | `docker pull opena2a/dvaa` |
+| [**AIM**](https://github.com/opena2a-org/agent-identity-management) | Agent Identity Management -- identity and access control for AI agents | Self-hosted |
+| [**AI Browser Guard**](https://github.com/opena2a-org/AI-BrowserGuard) | Detect and control AI agents in the browser | Chrome Web Store |
+| [**DVAA**](https://github.com/opena2a-org/damn-vulnerable-ai-agent) | Damn Vulnerable AI Agent -- security training target | `docker pull opena2a/dvaa` |