{"_id":"@aayushcodebook/agentscan","name":"@aayushcodebook/agentscan","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aayushcodebook/agentscan","version":"0.1.0","description":"Cross-agent security posture scanner for self-hosted AI agents (OpenClaw, Hermes). 19 checks across exposure, gateway auth, secrets, CVEs, and malicious skills (taint + prompt-injection analysis) — graded A–F, mapped to CWE/OWASP-LLM/MITRE ATLAS. Zero dep","bin":{"agentscan":"bin/agentscan.js"},"type":"commonjs","main":"src/index.js","scripts":{"start":"node bin/agentscan.js","test":"node test/run.js"},"keywords":["openclaw","hermes","ai-agent","agent-security","security","scanner","llm-security","prompt-injection","supply-chain-security","sarif","devsecops","shadow-ai","audit"],"engines":{"node":">=16"},"license":"MIT","gitHead":"d6c09a36bea5837d032ad414b367838832e991d5","_id":"@aayushcodebook/agentscan@0.1.0","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-eTkgP6Nh6DTi4jp5gLoQo9Tkb3QSuVWOJxMqyStPFOUR5p6xkjGpaZU0/2TulQ8w1ypZHnFXeJpZGl+wFkejdw==","shasum":"6cf3c5f9d0906b446defce0a1be01b61b0d5ef49","tarball":"https://registry.npmjs.org/@aayushcodebook/agentscan/-/agentscan-0.1.0.tgz","fileCount":43,"unpackedSize":178195,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBFR2NrLjzSuzqOT0Uurhdr+1WvtgLIPKnfyP0Eg8q5bAiBeK28JZHh3VXxcl59OIk8ueA9jPBOF4gdSORyUA+EMUw=="}]},"_npmUser":{"name":"aayushcodebook","email":"gaikwads1103@gmail.com"},"directories":{},"maintainers":[{"name":"aayushcodebook","email":"gaikwads1103@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agentscan_0.1.0_1781359905099_0.4264574815917659"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-13T14:11:44.934Z","0.1.0":"2026-06-13T14:11:45.296Z","modified":"2026-06-13T14:11:45.482Z"},"maintainers":[{"name":"aayushcodebook","email":"gaikwads1103@gmail.com"}],"description":"Cross-agent security posture scanner for self-hosted AI agents (OpenClaw, Hermes). 19 checks across exposure, gateway auth, secrets, CVEs, and malicious skills (taint + prompt-injection analysis) — graded A–F, mapped to CWE/OWASP-LLM/MITRE ATLAS. Zero dep","keywords":["openclaw","hermes","ai-agent","agent-security","security","scanner","llm-security","prompt-injection","supply-chain-security","sarif","devsecops","shadow-ai","audit"],"license":"MIT","readme":"# agentscan\n\n**The cross-agent security posture scanner for self-hosted AI agents.**\n\nMost agent-security tools scan one skill, for one agent, before you install it.\nagentscan audits your **whole running install** — and works across **OpenClaw,\nHermes, and more** from a single tool. One command runs a framework-mapped\nposture assessment — **19 checks plus compound-risk correlation** — covering\nnetwork exposure, gateway auth, CVEs, secrets, SSRF, sandboxing, *and* malicious\nskills/plugins (with taint analysis + prompt-injection detection). It maps every\nfinding to CWE / OWASP LLM Top 10 / MITRE ATLAS, grades your setup **A–F**, and\nemits **SARIF** for CI. Everything runs on your machine — nothing is ever\nuploaded, and there are **zero dependencies** so you can read every line before\nyou trust it.\n\nValidated against real, default installs of **both** OpenClaw and Hermes — each\ngrades **B** with specific, actionable findings and **zero false alarms** (incl.\nacross 300+ real bundled skills).\n\n```bash\nnpx @aayushcodebook/agentscan\n```\n\n```\n  OpenClaw  ~/.openclaw   F  0/100\n  ──────────────────────────────────────────────────\n  ● FAIL  CHAIN: network-exposed AND unauthenticated gateway (RCE-class)   CRIT\n       CWE-306,CWE-668 · LLM06:2025 · AML.T0049,AML.T0012\n  ● FAIL  Agent version vs. known security advisories (CVEs)   CRIT\n       CWE-1395 · LLM03:2025\n       Installed version 3.0.0 is affected by CVE-2026-25253 (CVSS 8.8)…\n  ● FAIL  Malicious or suspicious skills & plugins   CRIT\n  ● FAIL  Gateway authentication (is the local API/WebSocket protected?)   CRIT\n  …\n  posture grade  F  0/100\n  coverage: 13/15 checks ran\n```\n\n## What it checks\n\nEach finding is tagged with its **CWE**, **OWASP LLM Top 10 (2025)**, and where\napplicable a **MITRE ATLAS** technique, and carries an intrinsic severity used\nfor scoring.\n\n| Check | Maps to | Why it matters |\n|-------|---------|----------------|\n| **Network exposure** | CWE-668 · ATLAS T0049 | Is the port reachable beyond localhost? (63% of public instances are.) |\n| **Tunnel exposure** | CWE-668 · LLM06 | A localhost-bound agent fronted by Tailscale Funnel / ngrok / cloudflared is on the public internet anyway — the bind-address blind spot. |\n| **Gateway authentication** | CWE-306/307 · LLM06 | Open port + no/weak auth = the ClawJacked/ClawBleed (CVE-2026-25253) precondition. |\n| **Access policy** | CWE-284 · LLM06 | `dmPolicy: open` / `allowFrom: [\"*\"]` lets any stranger on a channel command the agent. |\n| **CORS** | CWE-942 | A wildcard origin lets any website you visit call the agent's API. |\n| **Plaintext credentials** | CWE-312 · LLM02 | API keys/passwords stored in cleartext config. |\n| **Secret redaction** | CWE-532 · LLM02 | If redaction is off, secrets in tool output leak into transcripts and on-disk logs. |\n| **Secret file permissions** | CWE-732 | A key in `.env` is only safe if the file isn't world-readable. |\n| **Secrets in git** | CWE-540 · LLM02 | Agent home is a repo and secrets aren't `.gitignore`d → committed/pushed. |\n| **Version vs CVEs** | CWE-1395 · LLM03 | Running a build with a published advisory (feed-updatable; ships with the 2026 OpenClaw CVEs). |\n| **Malicious skills & plugins** | CWE-506 · LLM01/LLM03 · ATLAS T0010 | Signature-discovered (`SKILL.md`/`openclaw.plugin.json`), matched to the ClawHavoc blocklist, **taint-analyzed** (does a secret actually *flow* into a network/exec sink?), **prompt-injection-scanned** in the SKILL.md *text* (invisible/bidi unicode, hidden-comment instructions, role-hijack/override, exfil prompts), and **integrity-verified** (a \"first-party\" skill is trusted only if its bytes hash-match the original; impostors are caught). SKIP (never pass) if nothing found. |\n| **MCP supply chain** | CWE-829 · LLM03 | Remote MCP tool servers are third-party code in the agent's trust boundary. |\n| **SSRF / private URLs** | CWE-918 · LLM06 | If private-URL access is on, a poisoned link can reach internal hosts or the cloud-metadata endpoint (169.254.169.254). |\n| **Command-content scanner** | CWE-693 · LLM06 | Hermes pre-screens shell commands (Tirith); flags it disabled or fail-open. |\n| **Sandboxing / agency** | CWE-250 · LLM06 | Unsandboxed tools (or running as root) turn one bad instruction into full machine access. |\n| **Command/exec policy** | CWE-250 · LLM06 | Unrestricted shell (`tools.exec.security=\"full\"`, empty command allowlist) is the path from prompt injection to RCE. |\n| **Approvals (HITL)** | CWE-250 · LLM06 | Auto-approving high-impact actions removes the last human gate against a hijacked agent. |\n| **Prompt-injection exposure** | CWE-77 · LLM01 · ATLAS T0051 | Posture: untrusted input × capability × weak gating. Honest that a static scan can't *prove* an injection path. |\n| **Audit logging** | CWE-778 | No record of agent actions = no incident response, no SOC2/HIPAA/GDPR. |\n\n**Compound-risk correlation.** Individually-yellow findings can be a critical\nchain. agentscan names them — e.g. *exposed + unauthenticated* (RCE-class,\nCVE-2026-25253), *exposed + open command policy*, *untrusted input + a live\nmalicious extension*.\n\n**Posture score & grade.** Start at 100, subtract severity-weighted penalties\n(fail = full, warn = half, **skipped = ¼**, so uncertainty still costs), floored\nat 0, banded A–F. Coverage is reported separately so a high score on thin\ncoverage can't masquerade as safety.\n\n## Continuous monitoring (free)\n\nA scan is point-in-time, but the risky moment is *after* setup — when you install\na new skill or change config. Re-run on a schedule and get alerted only when your\nposture gets **worse**. No extra tooling — just `agentscan`, a scheduler, and a diff.\n\nA cron one-liner that re-scans daily and notifies on any new finding (drop in\ngrade or a new fail), comparing against the last run:\n\n```bash\n# crontab -e  →  scan at 8am daily; alert only if the grade/score regresses\n0 8 * * * cur=$(npx @aayushcodebook/agentscan@latest --quiet 2>/dev/null); prev=$(cat ~/.agentscan/last 2>/dev/null); \\\n  echo \"$cur\" > ~/.agentscan/last; [ \"$cur\" != \"$prev\" ] && \\\n  printf '%s\\n' \"$cur\" | grep -qE 'AT RISK|fail' && \\\n  osascript -e \"display notification \\\"$cur\\\" with title \\\"agentscan\\\"\" 2>/dev/null || true\n```\n\nOn Linux, swap the `osascript` line for `notify-send \"agentscan\" \"$cur\"` (or pipe to\nSlack/email). In CI, the GitHub Action in `examples/agentscan-scan.yml` does the\nsame on a schedule and uploads SARIF.\n\nA built-in `agentscan --watch` (file-watch the agent's config + skills dirs, scan\nthe moment something changes) is on the roadmap — open an issue if you'd use it.\nLive behavioral monitoring (catching an exfil or injection *as it happens*) is a\nseparate, bigger effort, not part of this CLI.\n\n### How it relates to native tools\n\nagentscan is **complementary** to an agent's own auditor, not a replacement.\nOpenClaw's built-in `openclaw security audit --deep` goes far deeper on\nOpenClaw-specific config hardening (filesystem ACLs, hooks, Docker sandbox\ninternals) and can auto-fix — run it. agentscan's distinct value is **cross-agent\ncoverage** (OpenClaw *and* Hermes), a **curated malicious-skill blocklist** and\n**CVE advisory feed** (threat intel a built-in `doctor` won't maintain), and\n**framework-mapped, SARIF output** for security teams and CI. Use both.\n\nA clean result means none of *these* known issues were found. It is not a\nguarantee of overall security — notably, prompt injection is assessed as\n*posture*, not proven absent, and a native `--deep` audit will catch\nconfig-hardening details agentscan doesn't.\n\n## Usage\n\n```bash\nnpx @aayushcodebook/agentscan                      # scan auto-detected installs\nnpx @aayushcodebook/agentscan --path ~/my-agent    # also scan a custom location (repeatable)\nnpx @aayushcodebook/agentscan --json               # full findings + score + framework tags (JSON)\nnpx @aayushcodebook/agentscan --sarif              # SARIF 2.1.0 for GitHub code scanning / CI\nnpx @aayushcodebook/agentscan --quiet              # one-line graded verdict\nnpx @aayushcodebook/agentscan --update-feed        # refresh blocklist + CVE advisory feeds\nnpx @aayushcodebook/agentscan --help\n```\n\n### Exit codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | all green (or no agent found) |\n| `1` | warnings only — review recommended |\n| `2` | critical issues — fix now |\n| `3` | scanner error |\n\nUseful in CI: `npx @aayushcodebook/agentscan --quiet || echo \"agent needs attention\"`.\n\n## Privacy\n\nagentscan reads local files and lists local sockets to produce the report. It\nmakes **no network calls** and uploads nothing. The malicious-skill blocklist\nships offline inside the package. You can confirm all of this by reading\n`src/` — it's a few hundred lines of plain Node with no third-party packages.\n\n## Supported agents\n\nLayouts in `src/data/targets.js` are taken from each project's official docs:\n\n| Agent | Config | Default port | Bind setting | Extensions |\n|-------|--------|--------------|--------------|------------|\n| **OpenClaw** | `~/.openclaw/openclaw.json` (JSON5), `~/.openclaw/.env`; legacy `~/.clawdbot/` | `18789` | `gateway.bind`: `loopback` (safe) / `lan` / `tailnet` / `custom` | skills (`SKILL.md`) + plugins (`openclaw.plugin.json`) |\n| **Hermes Agent** | `~/.hermes/config.yaml`, `~/.hermes/.env` | `8642` API, `9119` dashboard | `API_SERVER_HOST` env var (`127.0.0.1` safe, `0.0.0.0` exposed) | skills (`SKILL.md`, nested by category) |\n\nAdding another agent is one entry in `src/data/targets.js` (its config paths,\ndefault ports, bind model, and skill directory).\n\n## Updating the threat feed\n\nThe bundled malicious-skill blocklist + CVE advisories are a *floor*. Refresh\nthem without upgrading the package:\n\n```bash\nagentscan --update-feed\nagentscan --update-feed --feed-url https://your-mirror/blocklist.json\n```\n\nTrust guarantees (see `src/feed.js`):\n\n- A **scan makes zero network calls** — it reads the bundled list or a feed you\n  explicitly fetched earlier, whichever is newer. `--update-feed` is the only\n  command that touches the network.\n- The bundled version is a **downgrade floor**: a stale or tampered (e.g.\n  emptied) cache is refused, so detection can't be silently weakened.\n- A fetch failure **falls back to the bundle** and exits non-zero.\n\n## Contributing\n\nIssues and PRs welcome — especially new agent definitions (`src/data/targets.js`),\nblocklist/CVE entries, and false-positive reports. The whole tool is dependency-free\nand meant to be read end-to-end; `node test/run.js` runs the suite.\n\n## License\n\nMIT.\n","readmeFilename":"README.md","_rev":"1-5cbe2e3a2db821c6cffc74e42bc47b9a"}