Skip to content
Back to search

hackmyagent

Metasploit for AI agents: scan, attack, and fix AI agents and MCP servers. Open source security toolkit.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/opena2a-org--hackmyagent/badge.svg)](/listings/opena2a-org--hackmyagent)

HTML

<a href="/listings/opena2a-org--hackmyagent"><img src="/api/listings/opena2a-org--hackmyagent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx hackmyagent secure
  my-project  v1.0.0 · library · 47 files analyzed
  3 critical issues found

  Security  ━━━━━━━━━━━━━━━━━━━━ 42/100

  ── Observations ────────────────────────────────────────────
  Surfaces    library · 47 files
  Checks      320 static · 12 semantic (NanoMind AST) · 0 skipped
  Categories  credentials (3 critical) · MCP (2 high) · 18 others clear
  Verdict     Not safe to ship. Fix 3 critical issues before using this in production.

  ── Findings ────────────────────────────────────────────────
  │ CRITICAL  Exposed API key in .env
  │ .env:3
  │ Anthropic API key (sk-ant-api03-****) detected in plaintext.
  │ Verify: sed -n '3p' '.env'
  │ Fix: hackmyagent secure --fix

No config files. No flags required. Exit code 1 if any critical or high finding fires.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 165 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # HackMyAgent
  2. [![Status: stable](https://img.shields.io/badge/status-stable-green)](STATUS.md)
  3. [![npm version](https://img.shields.io/npm/v/hackmyagent.svg)](https://www.npmjs.com/package/hackmyagent)
  4. [![Tests](https://github.com/opena2a-org/hackmyagent/actions/workflows/test-matrix.yml/badge.svg?branch=main)](https://github.com/opena2a-org/hackmyagent/actions/workflows/test-matrix.yml)
  5. [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
  6. > **[OpenA2A](https://github.com/opena2a-org)**: [CLI](https://github.com/opena2a-org/opena2a) · **HackMyAgent** · [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)
  7. [Website](https://hackmyagent.com) · [Demos](https://opena2a.org/demos) · [Discord](https://discord.gg/uRZa3KXgEn)
  8. Security scanner for AI agents. It finds the shadow AI on a machine, scans agent projects and packages for credentials, risky MCP configs, prompt injection and weak governance, and tests agents with attack payloads.
  9. ## Quick start
  10. Scan the project you are in:
  11. ```bash
  12. npx hackmyagent secure
  13. ```
  14. ```
  15. support-agent v1.0.0 · library · 5 files analyzed
  16. [...]
  17. ── Observations ────────────────────────────────────────────
  18. Surfaces library · 5 semantic artifacts · all 5 artifacts reached 0-6 of 7 analyzer families
  19. Checks 261 static declared · 63 of 63 check groups ran · 5 semantic (NanoMind AST, 0-6 of 7 analyzer families) · 5 files read by static checks
  20. [...]
  21. ── Findings ────────────────────────────────────────────────
  22. [...]
  23. │ CRITICAL Overprivileged MCP server scope
  24. │ .mcp.json:5
  25. │ Overprivileged filesystem access allows the agent (or an attacker via prompt injection) to read sensitive files like SSH keys, credentials, and system configs.
  26. │ Verify: sed -n '5p' /home/dev/workspace/support-agent/.mcp.json
  27. │ Fix: Scope "filesystem" to the project directory: replace "/" with "./" or a specific subdirectory.
  28. [...]
  29. Path forward: 53 -> 92 by fixing 1 critical + 3 high
  30. ```
  31. No config file or flag is needed. `[...]` marks omitted lines. The full output, the sample workspace and the build that produced it are in [docs/quick-start-capture.txt](docs/quick-start-capture.txt). The run exits 1 because a critical or high finding fired.
  32. <!-- chooser:start docs/chooser.json -->
  33. ## What do you want to check?
  34. - **My own project, before I ship it:** `npx hackmyagent secure`. Next: `npx hackmyagent secure --fix`.
  35. - **A package, repository or skill, before I install it:** `npx hackmyagent check <target>`. Next, for a local copy: `npx hackmyagent secure <dir> --fix`.
  36. - **A running agent endpoint you own:** `npx hackmyagent attack <url>`. Next, with every payload: `npx hackmyagent attack <url> --intensity aggressive`.
  37. - **One text, such as a pull request body:** `npx hackmyagent scan-text <file>`. Next, in a pipeline: `npx hackmyagent scan-text - --as pr-body --json`.
  38. - **Every agent project under this folder:** `npx hackmyagent detect`. Next, for one project: `npx hackmyagent secure <project>`.
  39. - **More.** A SOUL.md governance file: `npx hackmyagent scan-soul`. Attack payloads to run yourself against a skill, MCP config or SOUL.md: `npx hackmyagent red-team <file>`. MCP endpoints a host you own exposes: `npx hackmyagent scan <host>`.
  40. <!-- chooser:end -->
  41. ## What it finds
  42. - **Shadow AI**: the AI assistants, MCP servers and agent projects on a machine (`detect`). Example: `1 project MCP server with sensitive access`.
  43. - **Credentials and risky configuration**: 261 static checks, from MCP configs to supply chain and sandbox escape. Example: `CRITICAL Overprivileged MCP server scope`.
  44. - **Undeclared capabilities and scanner evasion**: 29 semantic checks over skills, prompts and configs. Example: `CRITICAL Data Exfiltration Surface`.
  45. - **Weak governance**: SOUL.md graded against a 9-domain model (`scan-soul`). Example: `Missing SOUL-IH-003 Role-play refusal`.
  46. - **Text that gives orders**: pull-request bodies, issues and comments (`scan-text`). Example: `TEXT-001 HIGH Instruction-override payload`.
  47. - **Attacks an agent falls for**: 164 adversarial payloads (`attack`). Example: `Prompt Injection: 2/2 successful` against a deliberately vulnerable agent.
  48. ## Usage
  49. ### Fix what a scan finds
  50. ```bash
  51. hackmyagent secure --fix --dry-run # preview the fixes
  52. hackmyagent secure --fix # apply them
  53. hackmyagent rollback # revert them
  54. ```
  55. Backups go to a store outside the project. Which checks it fixes, and where the backups live: [docs/SECURITY_CHECKS.md](docs/SECURITY_CHECKS.md#auto-fix-catalogue).
  56. - [hackmyagent secure: scores a sample agent project, then applies the fixes it can](docs/vhs/secure.gif): [text version](docs/vhs/secure-capture.txt), [provenance](docs/vhs/secure.json).
  57. ### Find the shadow AI on a machine
  58. ```bash
  59. npx hackmyagent detect
  60. ```
  61. ```
  62. workspace shadow ai audit · laptop · 2 agents · 3 agent projects
  63. [...]
  64. ── Shadow AI agents (3) ────────────────────────────────────
  65. project identified by mcp servers governance cred verdict
  66. support-agent Claude Code 2 mcp critical gov 0/100 cred no CRITICAL
  67. [...]
  68. ```
  69. One row per agent project, worst first. Full output: [docs/quick-start-capture.txt](docs/quick-start-capture.txt).
  70. ### Gate a pull request in CI
  71. ```yaml
  72. name: Agent Security
  73. on: [push, pull_request]
  74. jobs:
  75. scan:
  76. runs-on: ubuntu-latest
  77. steps:
  78. - uses: actions/checkout@v4
  79. - uses: actions/setup-node@v4
  80. with: { node-version: '20' }
  81. - run: npx hackmyagent secure --json > security-report.json
  82. - run: npx hackmyagent secure -b oasb-1 --fail-below 70
  83. ```
  84. `secure` exits 1 on a critical or high finding or a score below `--fail-below`, and 2 when it did not examine everything it found. Exit codes: [docs/commands.md](docs/commands.md#exit-codes). More recipes: [docs/ci.md](docs/ci.md).
  85. ### Use it from an AI assistant
  86. ```bash
  87. hackmyagent init-mcp --root /absolute/path/to/your/project
  88. ```
  89. That adds the server to Claude Code, Cursor or VS Code. Then ask the assistant: "Run a deep security scan on this project." The server reads only inside its roots, and no MCP tool writes to your files.
  90. ## Install
  91. ```bash
  92. npm install -g hackmyagent
  93. brew install opena2a-org/tap/hackmyagent
  94. ```
  95. Installing runs the install script of `onnxruntime-node`, which on Linux x64 downloads an execution-provider package from nuget.org. Node.js versions, skipping that download, and verifying a release: [docs/install.md](docs/install.md).
  96. ## Telemetry
  97. Usage telemetry is on by default, and `hackmyagent --version` says so on its second line: `Telemetry: on (opt-out: OPENA2A_TELEMETRY=off ...)`.
  98. - **Sent:** one event per command, to the OpenA2A Registry.
  99. - **Fields, and only these:** tool, version, install ID, event type, command name, success, duration, platform, Node major version.
  100. - **Failed command:** an error code is added to the command name.
  101. - **Install ID:** derived from a SHA-256 hash of the machine identifier, or of the hostname where none can be read.
  102. - **Not sent:** the raw identifier, file paths, scanned content, arguments beyond the command name, environment variables.
  103. - **Off under CI:** `CI`, `GITHUB_ACTIONS` and the other CI services' variables; `--version` then prints `Telemetry: off`.
  104. - **Off under test runners:** Vitest, Jest, `node --test`, `NODE_ENV=test`; `--version` then prints `Telemetry: off`.
  105. - **On under CI or a test runner:** only when `OPENA2A_TELEMETRY=on` is set for the run.
  106. - **Policy:** [opena2a.org/telemetry](https://opena2a.org/telemetry).
  107. ```bash
  108. OPENA2A_TELEMETRY=off hackmyagent secure # off for one run
  109. hackmyagent telemetry off # off on this machine; `telemetry status` shows the state
  110. OPENA2A_TELEMETRY_DEBUG=print hackmyagent secure # print each event on stderr before it is sent
  111. ```
  112. Sharing scan findings with the Registry is a separate opt-in (`--contribute`, or `contribute.enabled` in `~/.opena2a/config.json`; `--no-contribute` or `--ci` turns it off for a run). `hackmyagent telemetry off` covers usage telemetry only.
  113. ## Documentation
  114. - [Commands](docs/commands.md): the main commands and their flags, the MCP server, use through opena2a-cli, and exit codes.
  115. - [CI/CD](docs/ci.md): non-interactive runs, pull-request gates, credentials in git history, and scanning a pipeline's text.
  116. - [How it works](docs/how-it-works.md): discovery, static checks, the semantic layer, scoring, the simulation and the self-integrity check.
  117. - [Install](docs/install.md): Node.js versions, Homebrew, building from source, the install-time download, verifying provenance.
  118. - [Security checks](docs/SECURITY_CHECKS.md): check categories with representative checks, what each count includes, and what `--fix` changes.
  119. - [Use cases](docs/USE-CASES.md): scanning an agent, red-teaming an MCP server, securing OpenClaw and wiring a CI pipeline.
  120. - [Programmatic API](docs/PROGRAMMATIC_API.md): TypeScript entry points for the scanner, runtime protection and the NanoMind semantic compiler; [plugin authoring](docs/PLUGIN_API.md).
  121. - [Contributing](CONTRIBUTING.md): outside pull requests are welcome. Report security issues through [SECURITY.md](SECURITY.md), not a public issue.
  122. Part of the [OpenA2A](https://opena2a.org) security platform. Related: [opena2a-cli](https://github.com/opena2a-org/opena2a), the unified CLI that runs HackMyAgent behind `opena2a review`; [aicomply](https://github.com/opena2a-org/aicomply), which classifies PII, credentials and regulated data in agent I/O at runtime: HackMyAgent scans the code, aicomply guards the live stream. More in the [OpenA2A docs](https://opena2a.org/docs) and [research](https://research.opena2a.org).
  123. ## License
  124. Apache-2.0. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.