npm - hackmyagent - Versions diffs - 0.4.3 → 0.5.1 - Mend

hackmyagent 0.4.3 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -1,154 +1,191 @@
-# HackMyAgent CLI
+# 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-501%20passing-brightgreen)](https://github.com/opena2a-org/hackmyagent)
-**Part of [OpenA2A](https://opena2a.org)** — open-source security for AI agents
+**Find it. Break it. Fix it.**
-**Website:** [hackmyagent.com](https://hackmyagent.com) — Scan external infrastructure for exposed MCP endpoints, configs, and credentials
+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.
-## What's New — v0.4.3
+[Website](https://hackmyagent.com) | [Docs](https://hackmyagent.com/docs) | [OpenA2A](https://opena2a.org) | [Security Checks Reference](docs/SECURITY_CHECKS.md)
-**First scanner for [CVE-2026-25253](https://hackmyagent.com/blog/cve-2026-25253-detection)** (CVSS 8.8) — the OpenClaw WebSocket hijacking RCE.
-- **CVE-001:** Detect vulnerable OpenClaw versions (before v2026.1.29)
-- **CVE-002:** Control UI origin restrictions (defense-in-depth hardening)
-- **CVE-003:** CVE-2026-25157 — OS command injection via SSH path (CVSS 7.8)
-- **CVE-004:** CVE-2026-24763 — Docker PATH command injection (CVSS 8.8)
-- **SUPPLY-005–008:** ClawHavoc campaign IOCs (C2 IPs, malware filenames, ClickFix patterns)
-- **GATEWAY-007–008, CONFIG-007–009:** Config hardening (open DM wildcards, disabled sandbox, weak tokens)
-13 new checks. 147+ total.
-## Disclaimer
+---
-HackMyAgent performs passive reconnaissance only (port checks and HTTP requests) — it does not exploit vulnerabilities. However, please only scan systems you own or have permission to test. The authors assume no liability for misuse of this tool.
+## Quick Start
 ```bash
-npx hackmyagent check @publisher/skill     # verify a skill before installing
-npx hackmyagent secure                      # harden your agent setup (147+ checks)
-npx hackmyagent secure --fix                # auto-fix security issues
-npx hackmyagent scan example.com            # scan for exposed infrastructure
-npx hackmyagent attack --local              # red team with 55 attack payloads
-npx hackmyagent secure --benchmark oasb-1   # run OASB-1 security benchmark
+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
 ```
-## Two Ways to Scan
+No config files required. Works out of the box.
-| Tool | Use Case |
-|------|----------|
-| **[hackmyagent.com](https://hackmyagent.com)** | Scan external targets — check if your MCP servers, configs, or credentials are exposed on the internet |
-| **`npx hackmyagent secure`** | Scan local projects — harden your agent setup before deploying |
-## Why HackMyAgent?
+---
-CVE-2026-25253 turned every OpenClaw installation into a remote code execution target. 341 malicious skills were distributed through ClawHub. AI agent security is no longer theoretical — HackMyAgent helps you:
+## Table of Contents
+- [Installation](#installation)
+- [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)
-- **Check** skills before installing (publisher verification, permission analysis)
-- **Secure** your agent setup (147+ security checks with auto-remediation)
-- **Scan** external infrastructure (exposed MCP endpoints, leaked configs)
+---
 ## Installation
 ```bash
-# Use directly with npx
+# Run directly (no install needed)
 npx hackmyagent secure
-# Or install globally
+# Install globally
 npm install -g hackmyagent
-# Or add to your project
+# Add to project devDependencies
 npm install --save-dev hackmyagent
 ```
+**Requirements:** Node.js 18+
+---
 ## Commands
 ### `hackmyagent secure`
-Scan and harden your local agent setup with 147+ security checks across 31 categories.
+Scan and harden your local agent setup. 147 checks across 30 categories with auto-remediation.
 ```bash
-# Basic scan
-hackmyagent secure
+hackmyagent secure                            # basic scan
+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
+```
+<details>
+<summary>All 30 security categories</summary>
+| Category | Checks | What it detects |
+|----------|--------|-----------------|
+| CRED | 4 | Hardcoded API keys, tokens, passwords |
+| MCP | 10 | MCP server misconfigurations |
+| CLAUDE | 7 | Claude Code security issues |
+| NET | 6 | Network exposure, open ports |
+| PROMPT | 4 | Prompt injection vectors |
+| INJ | 4 | XSS, SQL injection, command injection |
+| ENCRYPT | 4 | Missing encryption at rest |
+| SESSION | 4 | Session management flaws |
+| AUDIT | 4 | Missing audit trails |
+| SANDBOX | 4 | Process isolation gaps |
+| TOOL | 4 | Tool permission boundaries |
+| AUTH | 4 | Authentication weaknesses |
+| DEP | 4 | Vulnerable dependencies |
+| ENV | 4 | Insecure environment variables |
+| GIT | 3 | Git security (gitignore, hooks) |
+| IO | 4 | Input/output validation |
+| LOG | 4 | Logging and monitoring gaps |
+| PERM | 3 | Overly permissive file permissions |
+| PROC | 4 | Process isolation issues |
+| RATE | 4 | Missing rate limiting |
+| SEC | 4 | Security headers |
+| API | 4 | API security issues |
+| VSCODE | 2 | VS Code configuration risks |
+| CURSOR | 1 | Cursor IDE configuration risks |
+| CVE | 4 | Known CVE detection |
+| GATEWAY | 8 | Gateway misconfigurations |
+| CONFIG | 9 | Insecure default settings |
+| SUPPLY | 8 | Supply chain attack vectors |
+| SKILL | 12 | Malicious skill/tool detection |
+| HEARTBEAT | 6 | Heartbeat/cron abuse |
-# Scan specific directory
-hackmyagent secure ./my-project
+</details>
-# Auto-fix issues
-hackmyagent secure --fix
+<details>
+<summary>Auto-fix capabilities</summary>
-# Preview fixes without applying
-hackmyagent secure --fix --dry-run
+**General (`hackmyagent secure --fix`):**
+| Check | Issue | Auto-fix |
+|-------|-------|----------|
+| CRED-001 | Exposed API keys | Replace with env var reference |
+| GIT-001 | Missing .gitignore | Create with secure defaults |
+| GIT-002 | Incomplete .gitignore | Add missing patterns |
+| 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-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/`.
+</details>
+---
-# Skip specific checks
-hackmyagent secure --ignore CRED-001,GIT-002
+### `hackmyagent fix-all`
-# JSON output for CI/CD
-hackmyagent secure --json
+Run all OpenA2A security plugins in sequence: scan, fix, report.
-# Show all checks (including passed)
-hackmyagent secure --verbose
+```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
 ```
-**Security Categories:**
-| Category | Checks | Description |
-|----------|--------|-------------|
-| CRED | 4 | Credential exposure detection |
-| MCP | 12 | MCP server configuration |
-| CLAUDE | 8 | Claude Code security |
-| NET | 6 | Network security |
-| PROMPT | 4 | Prompt injection defenses |
-| INJ | 4 | Input validation (XSS, SQL, cmd) |
-| ENCRYPT | 4 | Encryption at rest |
-| SESSION | 4 | Session management |
-| AUDIT | 4 | Audit trails |
-| SANDBOX | 4 | Process isolation |
-| TOOL | 4 | Tool permission boundaries |
-| AUTH | 4 | Authentication checks |
-| DEPS | 4 | Dependency security |
-| ENV | 4 | Environment variable safety |
-| GIT | 4 | Git security (.gitignore, secrets in history) |
-| IO | 4 | Input/output validation |
-| LOG | 4 | Logging and monitoring |
-| PERM | 4 | File permissions |
-| PROC | 4 | Process isolation |
-| RATE | 4 | Rate limiting |
-| SEC | 4 | General security headers |
-| API | 4 | API security |
-| VSCODE | 4 | VS Code configuration |
-| CURSOR | 4 | Cursor IDE configuration |
-| CVE | 4 | OpenClaw CVE detection |
-| GATEWAY | 8 | Gateway misconfigurations |
-| CONFIG | 9 | Insecure settings |
-| SUPPLY | 8 | Supply chain attacks |
-| SKILL | 12 | Malicious skill detection |
-| HEARTBEAT | 6 | Heartbeat/cron abuse |
-| WINDSURF | 3 | Windsurf IDE configuration |
+**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 | **Secretless** | Credential detection (10 patterns), env var replacement, AES-256-GCM encrypted store |
-**Exit Codes:**
-- `0` - No critical/high issues
-- `1` - Critical or high severity issues found
+**`--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's safety before installing.
+Verify a skill before installing it.
 ```bash
 hackmyagent check @publisher/skill-name
-hackmyagent check @anthropic/claude-mcp --verbose
 hackmyagent check @publisher/skill --json
-hackmyagent check @publisher/skill --offline  # skip DNS verification
+hackmyagent check @publisher/skill --offline    # skip DNS verification
 ```
-**Checks performed:**
-- Publisher identity via DNS TXT records
-- Permissions requested (filesystem, network, shell access)
-- Revocation status against global blocklist
+Checks: publisher identity (DNS TXT), permissions requested, revocation status.
-**Note:** Only scan systems you own or have permission to test.
-**Risk Levels:** `low`, `medium`, `high`, `critical`
+---
 ### `hackmyagent scan`
@@ -157,70 +194,45 @@ 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 --verbose
 hackmyagent scan example.com --json
 ```
-**Detects:**
-- Exposed MCP SSE/tools endpoints
-- Public configuration files
-- API keys in responses
-- Debug/admin interfaces
-**Scoring:** A (90-100), B (80-89), C (70-79), D (60-69), F (<60)
-### `hackmyagent attack`
-Red team your AI agent with adversarial security testing. 55 attack payloads across 5 categories.
-```bash
-# Local simulation (no API calls - test payloads locally)
-hackmyagent attack --local
-hackmyagent attack --local --system-prompt "You are a helpful assistant"
+Detects: exposed MCP SSE/tools endpoints, public configs, API keys in responses, debug interfaces.
-# Test an API endpoint
-hackmyagent attack https://api.example.com/v1/chat
-hackmyagent attack https://api.example.com --api-format anthropic
+Scoring: A (90-100), B (80-89), C (70-79), D (60-69), F (<60).
-# Filter by category or intensity
-hackmyagent attack --local --category prompt-injection
-hackmyagent attack --local --intensity aggressive
+> Only scan systems you own or have written authorization to test.
-# Custom payloads from a JSON file
-hackmyagent attack https://api.example.com --payload-file custom.json
+---
-# CI/CD gate — fail on vulnerabilities at or above severity threshold
-hackmyagent attack https://api.example.com --fail-on-vulnerable          # any finding
-hackmyagent attack https://api.example.com --fail-on-vulnerable medium   # medium+
-hackmyagent attack https://api.example.com --fail-on-vulnerable critical # critical only
+### `hackmyagent attack`
-# Output formats
-hackmyagent attack --local -f json
-hackmyagent attack --local -f sarif -o results.sarif
+Red team your AI agent with 55 adversarial payloads across 5 categories.
-# Verbose mode (show each payload result)
-hackmyagent attack --local --verbose
+```bash
+hackmyagent attack --local                                    # local simulation
+hackmyagent attack --local --system-prompt "You are helpful"  # with custom 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 -f sarif -o results.sarif           # SARIF output
+hackmyagent attack https://api.example.com --fail-on-vulnerable medium  # CI gate
 ```
-**Attack Categories:**
+<details>
+<summary>Attack categories and custom payloads</summary>
 | Category | Payloads | Description |
 |----------|----------|-------------|
-| `prompt-injection` | 12 | Manipulate agent behavior via malicious input |
-| `jailbreak` | 12 | Bypass safety guardrails and restrictions |
-| `data-exfiltration` | 11 | Extract sensitive information from the agent |
-| `capability-abuse` | 10 | Misuse agent tools and capabilities |
+| `prompt-injection` | 12 | Manipulate agent behavior via injected instructions |
+| `jailbreak` | 12 | Bypass safety guardrails and system constraints |
+| `data-exfiltration` | 11 | Extract sensitive data, system prompts, credentials |
+| `capability-abuse` | 10 | Misuse agent tools for unintended actions |
 | `context-manipulation` | 10 | Poison agent context or memory |
-**Intensity Levels:**
-| Level | Description |
-|-------|-------------|
-| `passive` | Observation only, minimal risk |
-| `active` | Standard attack payloads (default) |
-| `aggressive` | Creative/risky payloads, full suite |
+Intensity: `passive` (observation only), `active` (default), `aggressive` (full suite).
-**Custom Payload File Format:**
+**Custom payloads:** Create a JSON file and pass with `--payload-file custom.json`:
 ```json
 {
@@ -239,302 +251,302 @@ hackmyagent attack --local --verbose
 }
 ```
-Only `id` and `payload` are required. See `--help` for all defaults.
+Only `id` and `payload` are required.
-**Output Formats:**
-- `text` - Human-readable report (default)
-- `json` - Machine-readable JSON
-- `sarif` - SARIF 2.1.0 for GitHub Security tab integration
-- `html` - Standalone HTML report
+</details>
-**Risk Scoring:**
-- 0-24: LOW - Minor issues, agent is reasonably secure
-- 25-49: MEDIUM - Some vulnerabilities, review recommended
-- 50-69: HIGH - Significant vulnerabilities, action required
-- 70-100: CRITICAL - Severe vulnerabilities, immediate action needed
+Output formats: `text`, `json`, `sarif` (GitHub Security tab), `html`.
+---
 ### `hackmyagent secure --benchmark`
-Run the [OASB-1](https://oasb.ai/oasb-1) (Open Agent Security Benchmark) — 46 controls across 10 categories that measure how secure your AI agent setup is.
+Run the [OASB-1](https://oasb.ai/oasb-1) (Open Agent Security Benchmark) — 46 controls across 10 categories.
 ```bash
-# Run benchmark (L1 by default)
-hackmyagent secure --benchmark oasb-1
+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 -v           # verbose (every control)
+hackmyagent secure -b oasb-1 -f html -o report.html  # HTML report
+hackmyagent secure -b oasb-1 --fail-below 70          # CI gate
+```
-# Target specific directory
-hackmyagent secure ./my-project --benchmark oasb-1
+<details>
+<summary>OASB-1 categories and maturity levels</summary>
-# Different maturity levels
-hackmyagent secure -b oasb-1 -l L1    # Essential (26 controls)
-hackmyagent secure -b oasb-1 -l L2    # Standard (44 controls)
-hackmyagent secure -b oasb-1 -l L3    # Hardened (46 controls)
+| # | Category | Controls |
+|---|----------|----------|
+| 1 | Identity & Provenance | 4 |
+| 2 | Capability & Authorization | 5 |
+| 3 | Input Security | 5 |
+| 4 | Output Security | 4 |
+| 5 | Credential Protection | 5 |
+| 6 | Supply Chain Integrity | 5 |
+| 7 | Agent-to-Agent Security | 4 |
+| 8 | Memory & Context Integrity | 4 |
+| 9 | Operational Security | 5 |
+| 10 | Monitoring & Response | 5 |
-# Verbose — see every control with pass/fail/unverified status
-hackmyagent secure -b oasb-1 -v
+**Maturity levels:** L1 Essential (26 controls), L2 Standard (44), L3 Hardened (46).
-# Filter by category
-hackmyagent secure -b oasb-1 --category "Credential Protection"
+**Ratings:** Certified (100%), Compliant (L1=100% + L2>=90%), Passing (>=90%), Needs Improvement (>=70%), Failing (<70%).
-# Output formats
-hackmyagent secure -b oasb-1 -f json
-hackmyagent secure -b oasb-1 -f sarif -o results.sarif
-hackmyagent secure -b oasb-1 -f html -o report.html
-hackmyagent secure -b oasb-1 -f asp -o profile.asp.json
+</details>
-# CI/CD gate — exit 1 if compliance is below threshold
-hackmyagent secure -b oasb-1 --fail-below 70
-```
+Output formats: `text`, `json`, `sarif`, `html`, `asp` (Agent Security Profile).
-**OASB-1 Categories (46 controls):**
-| # | Category | Controls | What it checks |
-|---|----------|----------|----------------|
-| 1 | Identity & Provenance | 4 | Cryptographic identity, ownership, provenance chain |
-| 2 | Capability & Authorization | 5 | Least privilege, capability boundaries, human-in-the-loop |
-| 3 | Input Security | 5 | Prompt injection, input validation, URL/SSRF protection |
-| 4 | Output Security | 4 | Output validation, destructive op confirmation, exfiltration prevention |
-| 5 | Credential Protection | 5 | Hardcoded secrets, context window isolation, log redaction |
-| 6 | Supply Chain Integrity | 5 | Dependency scanning, lockfiles, rug pull protection, SBOM |
-| 7 | Agent-to-Agent Security | 4 | Mutual auth, message integrity, trust boundaries |
-| 8 | Memory & Context Integrity | 4 | Context injection, memory isolation, summarization security |
-| 9 | Operational Security | 5 | Non-root execution, sandboxing, network isolation, resource limits |
-| 10 | Monitoring & Response | 5 | Security logging, anomaly detection, kill switch, incident response |
-**Maturity Levels:**
-| Level | Controls | Purpose |
-|-------|----------|---------|
-| L1 - Essential | 26 | Baseline security every agent should meet |
-| L2 - Standard | 44 (L1 + 18) | Production-grade agent security |
-| L3 - Hardened | 46 (L2 + 2) | High-security environments, multi-modal threats |
-**Rating System:**
-| Rating | L1 Criteria | L2 Criteria | L3 Criteria |
-|--------|-------------|-------------|-------------|
-| Certified | 100% | L1=100% + L2=100% | All 100% |
-| Compliant | — | L1=100% + L2≥90% | L1=100% + L2≥90% |
-| Passing | ≥90% | L1≥90% | L1≥90% |
-| Needs Improvement | ≥70% | L1≥70% | L1≥70% |
-| Failing | <70% | L1<70% | L1<70% |
-**Output Formats:**
-- `text` — Terminal report with category breakdown (default)
-- `json` — Machine-readable JSON with full control details
-- `sarif` — SARIF 2.1.0 for GitHub Security tab and IDE integration
-- `html` — Standalone HTML report with donut chart, radar chart, and grades
-- `asp` — Agent Security Profile (portable security posture document)
-**Exit Codes:**
-- `0` — Rating is Passing or better (or compliance above `--fail-below` threshold)
-- `1` — Rating is Failing or Needs Improvement (or compliance below threshold)
+---
 ### `hackmyagent secure-openclaw`
-Scan OpenClaw/Moltbot installations with 47 specialized security checks and auto-remediation.
+47 specialized checks for OpenClaw/Moltbot installations.
 ```bash
-hackmyagent secure-openclaw              # scan default location
-hackmyagent secure-openclaw ~/.moltbot   # scan specific directory
-hackmyagent secure-openclaw --fix        # auto-fix gateway misconfigurations
-hackmyagent secure-openclaw --fix --dry-run  # preview fixes
-hackmyagent secure-openclaw --json       # JSON output for CI/CD
+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
 ```
-**Detects:**
-- CVE-2026-25253 vulnerable versions (before v2026.1.29)
-- Missing `controlUi.allowedOrigins` (patch alone isn't enough)
-- ClawHavoc C2 IP addresses and malware filenames
-- ClickFix social engineering patterns
-- Unsigned/malicious skills (ClawHavoc campaign patterns)
-- Reverse shell backdoors
-- Credential exfiltration (wallets, SSH keys, API keys)
-- Heartbeat/cron abuse
-- Gateway misconfigurations (GHSA-g8p2 vulnerability)
-- Disabled sandbox/approval confirmations
-**Auto-Fix (with `--fix`):**
-| Check | Before | After |
-|-------|--------|-------|
-| GATEWAY-001 | `0.0.0.0` | `127.0.0.1` (local-only) |
-| GATEWAY-003 | Plaintext token | `${OPENCLAW_AUTH_TOKEN}` env var |
-| GATEWAY-004 | Approvals disabled | Approvals enabled |
-| GATEWAY-005 | Sandbox disabled | Sandbox enabled |
-**Check Categories:**
-| Category | Checks | Description |
-|----------|--------|-------------|
-| SKILL | 12 | Malicious skill detection |
-| HEARTBEAT | 6 | Heartbeat/cron abuse |
-| GATEWAY | 8 | Gateway misconfigurations (4 auto-fixable) |
-| CONFIG | 9 | Insecure settings |
-| SUPPLY | 8 | Supply chain attacks |
-| CVE | 4 | OpenClaw CVE detection |
+Detects: CVE-2026-25253, ClawHavoc IOCs, reverse shells, credential exfiltration, gateway misconfigs, disabled sandbox.
 See [SECURITY_CHECKS.md](docs/SECURITY_CHECKS.md#openclaw-security-checks) for full documentation.
+---
 ### `hackmyagent rollback`
-Undo auto-fix changes.
+Undo auto-fix changes. Backups are created automatically in `.hackmyagent-backup/`.
 ```bash
-hackmyagent rollback              # rollback current directory
-hackmyagent rollback ./my-project # rollback specific directory
+hackmyagent rollback                # rollback current directory
+hackmyagent rollback ./my-project   # rollback specific directory
+```
+---
+## Plugin Architecture
+HackMyAgent uses a modular plugin system built on [`@opena2a/plugin-core`](packages/plugin-core). Each plugin implements `scan()` to detect issues and `fix()` to remediate them.
+### Packages
+| Package | npm | Description |
+|---------|-----|-------------|
+| [`@opena2a/plugin-core`](packages/plugin-core) | — | Plugin interface, registry, shared types |
+| [`@opena2a/aim-core`](packages/aim-core) | — | Ed25519 identity, audit logging, capability policy, trust scoring |
+| [`@opena2a/secretless-openclaw`](packages/secretless-openclaw) | — | Credential scanning (10 patterns), env var replacement, AES-256-GCM store |
+| [`@opena2a/signcrypt-openclaw`](packages/signcrypt-openclaw) | — | Ed25519 file signing, SHA-256 hash pinning, signature verification |
+| [`@opena2a/skillguard-openclaw`](packages/skillguard-openclaw) | — | Permission pinning, tamper detection, dangerous pattern scanning |
+### Writing a Plugin
+```typescript
+import type {
+  OpenA2APlugin,
+  PluginMetadata,
+  PluginStatus,
+  Finding,
+  Remediation,
+  FixOptions,
+  PluginInitOptions,
+} from '@opena2a/plugin-core';
+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,
+};
+export class MyPlugin implements OpenA2APlugin {
+  readonly metadata = metadata;
+  async init(options?: PluginInitOptions): Promise<void> {
+    // Access AIM Core for identity-aware audit logging:
+    // const aimCore = options?.aimCore;
+  }
+  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,
+      },
+    ];
+  }
+  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 }];
+    }
+    // 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 };
+  }
+  async uninstall(): Promise<void> {}
+}
+export function createPlugin(): MyPlugin {
+  return new MyPlugin();
+}
 ```
-Backups are automatically created in `.hackmyagent-backup/` with timestamps.
+Register the plugin in `@opena2a/plugin-core`:
+```typescript
+import { registerPlugin } from '@opena2a/plugin-core';
+import { createPlugin, metadata } from '@my-org/my-plugin';
+registerPlugin({
+  metadata,
+  create: createPlugin,
+});
+```
+### Trust Score
+AIM Core provides an 8-factor weighted trust score (0.0 to 1.0) for each agent:
+| 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 |
+Use `--with-aim` in `fix-all` to generate trust scores.
+---
 ## CI/CD Integration
 ### GitHub Actions
 ```yaml
-name: Security Scan
+name: Agent Security
 on: [push, pull_request]
 jobs:
-  security:
+  scan:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
+        with: { node-version: '20' }
       - run: npx hackmyagent secure --json > security-report.json
+      - run: npx hackmyagent fix-all --scan-only --json > plugin-report.json
       - uses: actions/upload-artifact@v4
-        with:
-          name: security-report
-          path: security-report.json
+        with: { name: security-reports, path: '*.json' }
 ```
-### GitHub Actions with Attack Mode (SARIF)
+### SARIF (GitHub Security Tab)
 ```yaml
-name: AI Agent Security
-on: [push, pull_request]
-jobs:
-  attack-scan:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-      - name: Run attack simulation
-        run: npx hackmyagent attack --local -f sarif -o attack-results.sarif --fail-on-vulnerable medium
-      - name: Upload SARIF to GitHub Security
-        uses: github/codeql-action/upload-sarif@v3
-        with:
-          sarif_file: attack-results.sarif
-  benchmark:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-      - name: Run OASB-1 benchmark
-        run: npx hackmyagent secure -b oasb-1 --fail-below 70
+- run: npx hackmyagent attack --local -f sarif -o results.sarif --fail-on-vulnerable medium
+- uses: github/codeql-action/upload-sarif@v3
+  with: { sarif_file: results.sarif }
 ```
 ### Pre-commit Hook
 ```bash
-# .git/hooks/pre-commit
 #!/bin/sh
+# .git/hooks/pre-commit
 npx hackmyagent secure --ignore LOG-001,RATE-001
 ```
-### JSON Output
-All commands support `--json` for machine-readable output:
+### JSON Piping
 ```bash
+# Filter critical findings
 hackmyagent secure --json | jq '.findings[] | select(.severity == "critical")'
-```
-## Supported Platforms
-- **Claude Code** - CLAUDE.md, skills, MCP servers
-- **Cursor** - .cursor/ rules, MCP configurations
-- **VSCode** - .vscode/mcp.json configurations
-- **Generic MCP** - Any MCP server setup
+# Count issues by category
+hackmyagent secure --json | jq '[.findings[].id | split("-")[0]] | group_by(.) | map({(.[0]): length}) | add'
+```
-## Security Check Reference
+---
-For the complete list of 147+ security checks with descriptions and remediation guidance, see [SECURITY_CHECKS.md](docs/SECURITY_CHECKS.md).
+## Exit Codes
-## Auto-Fix Capabilities
+| 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` |
-The following issues can be automatically fixed with `--fix`:
+---
-**General (`hackmyagent secure --fix`):**
-| Check ID | Issue | Auto-Fix Action |
-|----------|-------|-----------------|
-| CRED-001 | Exposed API keys | Replace with env var reference |
-| GIT-001 | Missing .gitignore | Create with secure defaults |
-| GIT-002 | Incomplete .gitignore | Add missing patterns |
-| 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 |
+## Supported Platforms
-**OpenClaw (`hackmyagent secure-openclaw --fix`):**
-| Check ID | Issue | Auto-Fix Action |
-|----------|-------|-----------------|
-| GATEWAY-001 | Bound to 0.0.0.0 | Bind to 127.0.0.1 |
-| GATEWAY-003 | Plaintext token in config | Replace with `${OPENCLAW_AUTH_TOKEN}` |
-| GATEWAY-004 | Approvals disabled | Enable approval confirmations |
-| GATEWAY-005 | Sandbox disabled | Enable sandbox mode |
+| 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 |
-Always use `--dry-run` first to preview changes. Backups are created automatically.
+---
 ## Environment Variables
 | Variable | Description |
 |----------|-------------|
 | `NO_COLOR` | Disable colored output |
-| `HACKMYAGENT_TIMEOUT` | Default timeout for scans (ms) |
-## Test Fixtures
-Sample projects with intentional security issues for testing:
-```bash
-# Test the scanner against example projects
-npx hackmyagent secure test-fixtures/insecure-api     # Score: 27/100
-npx hackmyagent secure test-fixtures/insecure-mcp     # Score: 0/100
-npx hackmyagent secure test-fixtures/insecure-library # Score: 60/100
-npx hackmyagent secure test-fixtures/clean-project    # Score: 100/100
-# Test auto-fix
-npx hackmyagent secure test-fixtures/insecure-api --fix
-```
-See [test-fixtures/README.md](test-fixtures/README.md) for details.
+---
 ## Contributing
-Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
 ```bash
-# Development setup
 git clone https://github.com/opena2a-org/hackmyagent.git
 cd hackmyagent
 npm install
-npm run build
-npm test
+npx turbo build     # build all 7 packages
+npx turbo test      # run 501 tests
 ```
-## License
+### Monorepo Structure
-Apache-2.0
+```
+packages/
+  cli/                      # CLI entry point (hackmyagent command)
+  core/                     # Scanner engine (147 checks)
+  aim-core/                 # Ed25519 identity, audit, policy, trust
+  plugin-core/              # Plugin interface and registry
+  secretless-openclaw/      # Credential scanner plugin
+  signcrypt-openclaw/       # Signing and hash pinning plugin
+  skillguard-openclaw/      # Permission and pattern scanner plugin
+```
 ---
-## Secure What You Find
+## License
-HackMyAgent finds vulnerabilities. **[AIM](https://github.com/opena2a-org/agent-identity-management)** fixes them — the open-source NHI platform for AI agents with cryptographic identity, governance, and access control.
+Apache-2.0
+---
-→ [Get started with AIM](https://opena2a.org/docs/quick-start) | [Learn about NHI governance](https://opena2a.org/nhi)
+Built by [OpenA2A](https://opena2a.org). HackMyAgent finds vulnerabilities. [AIM](https://github.com/opena2a-org/agent-identity-management) manages identity and access.