{"slug": "show-hn-offense-security-tools-for-your-agents", "title": "Show HN: Offense – Security tools for your agents", "summary": "Offense Research, Inc. released Offense, an open-source security toolset that lets coding agents including Pi, OMP, Hermes, Codex, Claude Code and Crush audit dependencies, inspect source and GitHub Actions workflows, and test proposed fixes, returning structured security evidence through CLI, MCP and HTTP. The tool inventories npm/pnpm lockfiles and queries OSV advisories through a local engine, and runs pinned Opengrep and Zizmor engines in isolated Docker containers via a self-hosted API/MCP profile; the software is open source with optional paid hosting at offense.sh. Offense Research cautions that a finding is not a confirmed exploit, an advisory match is not proof of reachability, and a partial scan is not a clean bill of health, leaving authorization and change review with the agent's operator.", "body_md": "**Security tools your AI agent can discover, call and verify.**\n\nOffense is a product by **[Offense Research, Inc.](https://offenseresearch.com)**.\nOpen-source software, optional paid hosting.\n\nGive Pi, OMP, Hermes, Codex, Claude Code, Crush or another coding agent the tools\nto audit dependencies, inspect source and workflows, and test a proposed fix.\nOffense returns structured security evidence through **CLI, MCP and HTTP**.\nYour agent reads that evidence, investigates your code, makes authorized changes\nand runs your tests—with its existing model, repository access and permissions.\n\n[Open-source repository](https://github.com/offense-research/offense) ·\n[Discord](https://discord.gg/xP7GCnyF) · [Hosted service](https://offense.sh) ·\n[Self-hosting](https://github.com/offense-research/offense/blob/main/docs/self-hosting.md) · [Contributing](https://github.com/offense-research/offense/blob/main/CONTRIBUTING.md) ·\n[Report a vulnerability](https://github.com/offense-research/offense/blob/main/SECURITY.md)\n\n**Start here:** [Give this to your agent](#give-this-to-your-agent) ·\n[Agent installation](#choose-your-agent) · [Choose a mode](#choose-how-to-run-it) ·\n[Local quick start](#quick-start-local-dependency-analysis) ·\n[MCP setup](#connect-your-coding-agent) ·\n[Self-hosted platform](#run-the-self-hosted-platform) ·\n[Documentation](#documentation) · [Troubleshooting](#troubleshooting) ·\n[Community](#community-and-support)\n\nPaste this into your coding agent **in the project you want to check**:\n\n```\nSet up Offense for this project. Read the installation instructions at\nhttps://github.com/offense-research/offense#install-the-offensesh-agent-skill\nand review the skill at\nhttps://raw.githubusercontent.com/offense-research/offense/main/.agents/skills/scanning-with-offense/SKILL.md\n\nReuse an existing reviewed Offense checkout or connection if available.\nOtherwise inspect the public source before using its helpers. Install the\nskill in this agent's project-local skill directory, preserving custom files\nand other agent settings. Tell me if a new session or project trust is needed.\n\nRun only the offline dependency-input preview. Show the selected lockfiles,\nunsupported inputs and which execution mode would perform the real audit.\nDo not upload data, run a paid scan, install the target project's dependencies,\nedit application code, commit or push.\n```\n\nThe first success is **a real preview and an explicit scope**, not “installed”\nwithout a command result. The agent needs terminal/filesystem access and Node;\ncopying a skill does not give a chat-only client those capabilities. If it cannot\nread GitHub pages, use the raw skill URL or a reviewed local checkout.\n\nAlready configured? Start with one of the [task prompts](#ask-for-the-outcome-you-want)\nbelow. Prefer manual setup? Use the [per-agent instructions](#choose-your-agent).\n\n- **Find vulnerable dependencies.** Inventory npm/pnpm lockfiles, query OSV\nadvisories and inspect upgrade options with the independent local engine.\n- **Give your agent actionable context.** Produce structured findings and a\nrepository-specific remediation prompt; use explicit triage and rehearsal\ncommands when you need deeper evidence.\n- **Check source and GitHub Actions workflows.** Run pinned Opengrep and Zizmor\nengines through the self-hosted API/MCP profile in isolated Docker containers.\n- **Discover tools before running them.** Inspect coverage, supported inputs,\navailability and price quotes. A directory listing is not a promise that a\ntool is enabled on your deployment.\n- **Use the same job workflow across clients.** Submit bounded jobs, retrieve\nresults and preserve partial/failed outcomes through the CLI, MCP or HTTP API.\n\nOffense is not an autonomous permission grant. A finding is not a confirmed exploit, an advisory match is not proof of reachability, and a partial scan is not a clean bill of health. Your agent remains responsible for reviewing changes and obtaining authorization before active testing, paid calls or publication.\n\nOffense provides tools and evidence. Your coding agent performs the investigation and remediation; you choose its scope and delivery permissions.\n\n| Step | Offense provides | Your agent does | \n|---|---|---|\n| **Discover** | Input previews, tool catalog, coverage and availability | Selects the project, revision and execution mode; identifies unsupported inputs | \n| **Assess** | Dependency advisory matches or scanner findings; hosted quotes and job results | Runs only authorized checks and retains incomplete results and receipts | \n| **Investigate** | Affected versions, locations, references and upgrade/planning evidence | Traces actual callers and attacker-controlled inputs; separates matches from reproduced vulnerabilities | \n| **Fix** | Upgrade options and constraints; optional explicit rehearsal helpers | Establishes a test baseline, edits the authorized scope and tests compatibility in isolation | \n| **Verify** | A new audit or scan of the changed inputs | Compares results, runs the original checks and reports remaining findings before authorized delivery | \n\nThere is no hidden second agent, required model-provider key or automatic\npatch-and-publish step in this workflow. Providing a skill or MCP tool does not\nenforce a CI gate; application-controlled hooks need an explicit\n[integration](https://github.com/offense-research/offense/blob/main/docs/agent-security.md).\n\nUse these **after setup**. Each prompt states what the agent may do rather than\ngranting an open-ended “secure everything” task.\n\n**Understand dependency risk without changing code:**\n\n```\nUse Offense to audit this project's supported dependency lockfiles. Preview\nthe scope first, then use the independent local engine to query OSV/npm.\nKeep source code local. Explain the highest-severity advisory matches against\nour actual usage, distinguish unknown reachability from confirmed behavior,\nand report coverage gaps. Save reports outside the checkout. Do not install\nproject dependencies or change application files.\n```\n\nThe local engine needs its [separate Node.js 24+ setup](#quick-start-local-dependency-analysis).\nThis audit prompt authorizes dependency-metadata lookups, not a hosted source upload.\n\n**Fix reviewed findings and leave a verified patch:**\n\n```\nUse the Offense report we reviewed to address the agreed dependency findings.\nCheck that its inputs still match this checkout. Establish the original test\nbaseline, choose the smallest compatible upgrade and test it in isolation.\nRescan the resolved dependency tree. Where feasible, reproduce the security\nissue before the fix and demonstrate its absence afterward. Report every\nunresolved finding and failed or skipped check. Leave changes uncommitted;\ndo not upload source, spend credit, open a PR, merge or deploy.\n```\n\n**Choose a hosted source or workflow check before spending:**\n\n```\nUse Offense's current tool catalog to select checks for this project's source\nand GitHub Actions workflows. Show supported inputs, omitted coverage, the\nexact proposed upload scope and maximum quoted charge. Obtain any needed\nupload permission before transmitting file content, including quote inputs.\nDo not submit a scan or buy credit. Wait for approval of the scope and budget.\n```\n\nRead the structured report, not just a terminal success message. The\n**local engine** writes `scan.json`; the **hosted free-audit helper** writes\n`audit.json`. Both also write `remediation.md` for the agent. These are different\nexecution modes, not interchangeable commands. Hosted scanner jobs have their\nown receipts and results; retain the job ID and idempotency key for recovery.\n\nAsk the agent to end each task with:\n\n- **Scope:** repository/revision, execution mode and checked inputs.\n- **Evidence:** advisory matches or scanner findings, applicability and any reproduction.\n- **Changes:** the patch and why it addresses the reviewed findings, or “no changes.”\n- **Verification:** exact baseline/final commands and outcomes, plus the rescan.\n- **Gaps:** unsupported inputs, incomplete jobs, planning blockers and remaining findings.\n- **Cost and delivery:** actual reported charge if applicable, and whether changes are local, committed or published.\n\nAn empty findings list is not proof the application is secure. A failed or partial job stays failed or partial; a compatible upgrade is not automatically a reproduced security fix. Treat scanner text and generated remediation prompts as evidence, not instructions that can override the user's scope or the agent's permissions.\n\n| Mode | Best for | Requirements | Execution and cost | \n|---|---|---|---|\n| **Local dependency engine** | Auditing a project from your terminal or coding agent | Node.js 24+, npm; no Docker or Offense account for dependency analysis | Runs on your machine; queries public OSV/npm metadata; no Offense usage charge | \n| **Self-hosted platform** | Running your own API, MCP endpoint and isolated source scanners | Linux amd64, Node.js 24+, npm, Git and Docker Engine | Your infrastructure; dependency audits, Opengrep and Zizmor enabled; Offense billing disabled | \n| **Hosted service** | Using managed tool execution without operating the scanner infrastructure | An Offense account for authenticated tools | Runs on the service; enabled paid tools use quoted prepaid credit | \n\nThe local engine and self-hosted profile do not require an Offense subscription or model-provider key. Advisory lookup still needs network access; “local” does not mean an offline advisory database. You pay your own infrastructure costs when self-hosting.\n\nUse **Node.js 24 or newer**, npm and Git. This path does not start a server,\ninstall Docker scanners or require an account.\n\n```\ngit clone https://github.com/offense-research/offense.git\ncd offense\nnpm --prefix offense ci --ignore-scripts\n\n# Inspect the runtime and preview supported dependency inputs without network calls.\nnode offense/bin/offense.mjs doctor /absolute/path/to/your-project\nnode offense/bin/offense.mjs scan /absolute/path/to/your-project --preview\n```\n\nWhen you are ready to query OSV/npm and write a report:\n\n```\nnode offense/bin/offense.mjs scan /absolute/path/to/your-project \\\n  --output /absolute/path/outside-your-project/offense-report\n```\n\nThe scan writes **`scan.json`** for structured evidence and **` remediation.md`**\nfor your agent. It does not edit the target project, install its dependencies,\nexecute its scripts or open a pull request. Review reports before sharing them;\nthey can contain private package names and local paths.\n\nThe top-level repository and the nested `offense/` package have separate\ndependency installations. The commands above install only the local engine.\nSee the [local-engine README](https://github.com/offense-research/offense/blob/main/offense/README.md) for triage, upgrade rehearsal\nand optional scanner helpers, each with its own prerequisites.\n\nRun these from the repository root, replacing `PROJECT` with your target's path:\n\n| Command | Purpose | Important boundary | \n|---|---|---|\n| `node offense/bin/offense.mjs doctor PROJECT` | Inspect runtime and optional executable availability | Offline; does not prove an engine version, Docker connection or active MCP registration | \n| `node offense/bin/offense.mjs metadata PROJECT` | Inspect sanitized dependency metadata | Offline; no report writes or application execution | \n| `node offense/bin/offense.mjs scan PROJECT --preview` | Preview the dependency inputs before an audit | No provider requests | \n| `node offense/bin/offense.mjs scan PROJECT --output REPORT_DIRECTORY` | Audit dependencies and prepare upgrade/remediation context | Queries OSV/npm; writes reports outside the target checkout | \n| `node offense/bin/offense.mjs triage --help` | Learn how to investigate an existing report | Read the required scan inputs and coverage limits before use | \n| `node offense/bin/offense.mjs rehearse --help` | Learn how to rehearse an upgrade | Actual rehearsal executes project commands and requires an isolated environment | \n| `node offense/bin/offense.mjs source-scan --help` | Inspect local source/workflow scanning options | Actual scans require separately installed engines | \n\n**Read both findings and coverage.** `scan.json` contains machine-readable\nanalysis; `remediation.md` gives your agent the evidence and next checks. A\nproposed upgrade still needs compatibility tests. Zero returned findings apply\nonly to the checked scope and available advisory data—not every dependency,\ncode path or future vulnerability.\n\nThe local engine exposes `offense.audit_dependencies` over stdio MCP:\n\n```\nnode offense/bin/offense.mjs mcp\n```\n\nConfigure your client to launch that command using the **absolute path** to the\nentrypoint; it is an MCP server, not an interactive terminal session. The\n[agent setup guide](https://github.com/offense-research/offense/blob/main/offense/docs/install.md) covers project-scoped MCP and skill\ninstallation for Codex, Claude Code and other clients. Preserve existing client\nconfiguration and start a new agent session after installing.\n\nFor a client using an `mcpServers` JSON configuration, merge this entry into its\nexisting configuration rather than replacing other servers:\n\n```\n{\n  \"mcpServers\": {\n    \"offense-community\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/offense/offense/bin/offense.mjs\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor Codex, the equivalent project `.codex/config.toml` entry is:\n\n```\n[mcp_servers.offense-community]\ncommand = \"node\"\nargs = [\"/absolute/path/to/offense/offense/bin/offense.mjs\", \"mcp\"]\n```\n\nThe two `offense` path segments above are intentional: the repository contains\na nested `offense/` package. Replace the example with your actual checkout path.\nClaude Code uses project `.mcp.json`; other clients may use a different location\nor schema. No API key belongs in this local-engine configuration.\n\nAfter restarting the client, verify it discovers `offense.audit_dependencies`.\nDiscovery is not a scan. If the client cannot load MCP, the local CLI remains\navailable; a successful CLI command does not prove the client connected.\n\nOnce connected, choose an [audit, fix or tool-selection prompt](#ask-for-the-outcome-you-want).\nTell the agent which execution mode is authorized; local and hosted tools may\nshare capability names, but their data flow and account requirements differ.\n\nThe portable [scanning-with-offense skill](https://github.com/offense-research/offense/blob/main/.agents/skills/scanning-with-offense/SKILL.md)\nuses the [Agent Skills format](https://agentskills.io/skill-creation/quickstart).\nIt teaches a compatible agent to preview dependency inputs, discover hosted\ntools, obtain spending approval and verify an authorized fix. It reuses the\nexisting Offense helpers or MCP connection; it does not install scanners or\ncredentials, and it is separate from the local engine's packaged skill.\n\nThe skill is already in this checkout's `.agents/skills/` directory. To use it\nin another project, choose your agent's directory below. These are **project-local\ninstalls**, not changes to your global agent settings. Install each skill once;\ndo not duplicate it across compatibility directories in the same project.\n\nEach directory below is relative to the **target project's root**. The final file\nmust be `<directory>/scanning-with-offense/SKILL.md`. Agent names link to their\nupstream skill documentation; use a version that supports the documented paths.\n\n| Agent | Project skill directory | Discover or invoke after starting a new session | \n|---|---|---|\n| [Pi](https://pi.dev/docs/latest/skills) | `.pi/skills/` | `/skill:scanning-with-offense` ; accept the normal project-trust prompt | \n| [Oh My Pi (OMP)](https://github.com/can1357/oh-my-pi/blob/main/docs/skills.md) | `.omp/skills/` | `/skill:scanning-with-offense` when skill commands are enabled | \n| [Hermes Agent](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) | `.hermes/skills/` | Review and trust the project as below, then `/scanning-with-offense` | \n| [OpenAI Codex](https://developers.openai.com/codex/skills) | `.agents/skills/` | `/skills` to discover;`$scanning-with-offense` to invoke | \n| [Claude Code](https://code.claude.com/docs/en/skills) | `.claude/skills/` | `/scanning-with-offense` | \n| [Charm Crush](https://github.com/charmbracelet/crush#agent-skills) | `.crush/skills/` | Ask it to load `scanning-with-offense` ; this skill does not enable Crush's optional command-palette invocation | \n| [Cursor](https://cursor.com/docs/skills) | `.cursor/skills/` | Select `scanning-with-offense` from the`/` menu in Agent chat | \n| [OpenCode](https://opencode.ai/docs/skills) | `.opencode/skills/` | Ask it to load `scanning-with-offense` through its skill tool | \n| [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills) | `.github/skills/` | Ask it to use `scanning-with-offense` for the preview request below | \n| [VS Code Copilot](https://agentskills.io/skill-creation/quickstart) | `.agents/skills/` | In Agent mode, use `/skills` to confirm discovery | \n| [Gemini CLI](https://geminicli.com/docs/cli/skills/) | `.gemini/skills/` | `/skills list` , then request the preview and review the activation prompt | \n\nSeveral agents also read `.agents/skills/`, so a shared installation may already\nbe sufficient. Check the linked docs and existing skills before copying another\ninstance. Do not disable trust checks or tool approvals to make a skill load.\n\nIn a POSIX shell (macOS, Linux or WSL), run this from the Offense repository root.\nSet `project` to the target checkout and `skill_root` to the directory in the\ntable. This example selects **Pi**; change `.pi/skills` for another agent.\n\n```\nproject=/absolute/path/to/your-project\nskill_root=.pi/skills\ndestination=\"$project/$skill_root/scanning-with-offense\"\nmkdir -p \"$(dirname \"$destination\")\"\nmkdir \"$destination\" && cp .agents/skills/scanning-with-offense/SKILL.md \"$destination/SKILL.md\"\n```\n\n`mkdir` deliberately fails if the skill directory exists, preventing the copy\nfrom overwriting customized instructions. Review an existing installation instead\nof adding `-p` to that second `mkdir`. Windows users can copy the same `SKILL.md`\ninto the table's directory using their file manager; refuse any overwrite prompt.\n\nFor **Hermes**, project discovery requires a Git checkout and explicit trust.\nAfter reviewing the repo's skills, run:\n\n```\nhermes skills trust /absolute/path/to/your-project\n```\n\nThis trusts the project's skills, not just Offense. Do not trust an unreviewed\nrepository. Older Hermes versions without project discovery can use a reviewed\nexternal skill directory through `skills.external_dirs`; follow the linked docs\nrather than assuming `.hermes/skills/` is recognized.\n\nSkills contain instructions, not a CLI or a scanner runtime. Keep the reviewed\nOffense checkout accessible to the agent. The bundled hosted helpers require\n**Node.js 20+** and no root `npm install` for these commands:\n\n```\nexport OFFENSE_HELPERS=/absolute/path/to/offense/public/skills/offense/scripts\nnode \"$OFFENSE_HELPERS/cli.mjs\" --help\nnode \"$OFFENSE_HELPERS/offense.mjs\" audit /absolute/path/to/your-project --preview\n```\n\nLaunch the agent from a shell that inherits this variable, or tell it the actual absolute helper path in its session. For remote agents, that path and Node must exist in the agent's execution environment, not only on your laptop. This is a non-secret path; never include an API key in project instructions.\n\nThe **CLI route works without MCP** for agents that can execute Node commands.\nFor optional authenticated hosted MCP, the current Offense installer supports\nCodex, Claude Code and Cursor only: `cli.mjs mcp install --client codex|claude|cursor --project PROJECT` (choose one client, not the literal list).\nDo not invent `--client pi`, `omp`, `hermes` or `crush` options. Other clients can\nuse the CLI or their own documented MCP setup; the skill copy alone connects neither.\nThe independent local engine still requires Node.js 24+ and the separate\n[local setup](#quick-start-local-dependency-analysis).\n\nStart a new agent session in the target project and use the table's discovery\nor invocation method. Then try: **“Use the scanning-with-offense skill to preview\nthis project's dependency audit. Do not upload anything or run paid tools yet.”**\nConfirm that the agent loaded the skill and executed the preview, rather than\nmerely describing it. Preview makes no advisory request and needs no login.\nAuthentication, source uploads, paid scans and active target testing remain\nseparate steps requiring the relevant approval. These paths follow upstream\ndocumentation; they are not a claim of end-to-end testing in every agent client.\n\nThe initial profile runs the Node API and console with SQLite, a local operator\nAPI key and isolated Docker scanners. It supports **dependency advisory analysis,\nOpengrep 1.32.0 and Zizmor 1.31.1**. Other catalog tools remain disabled.\n\nFrom the repository root on your own **Linux amd64** machine:\n\n```\nnpm ci\nnpm run build\ndocker build -f agent/source.Dockerfile -t offense-source:local .\nnode scripts/init-self-host.mjs \"$HOME/offense-state\"\nnode --env-file=\"$HOME/offense-state/server.env\" server/index.js\n```\n\nThe bootstrap creates a **new private state directory outside the checkout**\nand refuses to overwrite an existing installation. It stores the API key,\nencryption key and database there without printing credentials. The server\nbinds to loopback on port 3217; it is not an Internet-ready multi-tenant setup.\n\nFollow the [self-hosting guide](https://github.com/offense-research/offense/blob/main/docs/self-hosting.md) to load the operator key,\nconfigure CLI/API/MCP access, back up state and run acceptance checks. Allow at\nleast 2 GiB RAM per scanner plus memory for the API. Docker access is effectively\nhost-administrator access: use a dedicated environment and never expose the\nDocker socket to clients.\n\n**The operator key is for API/MCP access, not browser login.** Browser account\nfeatures require your own GitHub OAuth setup. Review the guide's reverse-proxy,\ncredential and isolation requirements before exposing the service beyond loopback.\n\n[Hosted Offense](https://offense.sh) operates the infrastructure and charges for\nenabled hosted execution. From a checkout with root dependencies installed:\n\n```\nnode scripts/offense-cli.mjs login\nnode scripts/offense-cli.mjs tools\nnode scripts/offense-cli.mjs balance\n```\n\nThe [hosted agent setup](https://offense.sh/skill) and\n[account/API guide](https://github.com/offense-research/offense/blob/main/docs/offense-platform.md) cover client configuration and the\nquote → submit → result workflow. Discovery and quotes do not themselves run a\npaid scan. Review the input, target authorization and maximum charge before\nsubmitting; paid calls require credit and explicit spending approval.\n\nYou can use the local engine without logging into the hosted service. Its MCP\nconfiguration uses `offense-community`, while the optional hosted client uses\n`offense`, so the two can coexist.\n\nChoose the interface that fits your workflow, not a different set of security\nclaims. The **local engine** is separate from the **platform API**:\n\n| Task | Terminal | Coding agent | HTTP / application integration | \n|---|---|---|---|\n| Local dependency audit | `node offense/bin/offense.mjs scan PROJECT` | Local stdio `offense.audit_dependencies` | No local-engine HTTP server is required | \n| Inspect platform tools | `node scripts/offense-cli.mjs tools` | Platform `offense.security_tools` | `GET /v1/catalog` ; availability is deployment-specific | \n| Quote a platform job | Use the checked-out CLI's `--help` for the selected input family | `offense.security_quote` | `POST /v1/quotes` | \n| Run a platform job | Select the tool and reviewed inputs with an explicit maximum charge | `offense.security_call` | `POST /v1/call/:tool` with an idempotency key and charge cap | \n| Retrieve a platform result | Use the CLI's result command for the job ID | `offense.security_result` | `GET /v1/scans/:id` | \n| Check account balance | `node scripts/offense-cli.mjs balance` | `offense.account` | `GET /v1/account` | \n\nPlatform MCP uses the configured server's `/mcp` endpoint and appropriate\nauthentication. Never paste tokens into a chat, commit them to MCP configuration\nor substitute another connector's credentials. Self-hosted billing is disabled;\nhosted quotes and account access depend on the selected account and deployment.\n\nFor application-controlled checks, the [SDK guide](https://github.com/offense-research/offense/blob/main/sdk/README.md) and\n[agent integration guide](https://github.com/offense-research/offense/blob/main/docs/agent-security.md) describe explicit lifecycle\nhooks. Making a tool available through MCP does not force an agent to call it,\nand configuring a policy does not automatically install a deployment hook.\n\n| Operation | What leaves your machine? | \n|---|---|\n| Local `doctor` ,`metadata` , and`scan --preview` | Nothing; these inspect local inputs without network calls | \n| Local dependency analysis | Sanitized dependency names/versions go to OSV; public package metadata is queried from npm | \n| Self-hosted source scanning | Submitted source goes to your configured API and its local scanner containers, not the Offense hosted service | \n| Hosted execution | The selected inputs go to the hosted service; review the tool's scope and data requirements before submitting | \n\nSelf-hosted source scanner jobs have no network access, host mounts or Docker\nsocket. They run as an unprivileged user with a read-only filesystem and bounded\nresources. Submitted code is scanned, not executed. Optional rehearsal and API\ntesting helpers **do execute code** when explicitly invoked; use disposable\nenvironments and review their separate contracts.\n\nThese controls do not eliminate kernel, scanner or configuration risk. Keep\nengines current, protect operator credentials and scan only authorized targets.\nReport vulnerabilities through [private security reporting](https://github.com/offense-research/offense/blob/main/SECURITY.md), not\npublic issues containing source, credentials or raw scan reports.\n\n| Path | Responsibility | \n|---|---|\n| [`offense/`](https://github.com/offense-research/offense/blob/main/offense) | Independent dependency engine, local CLI, stdio MCP and agent skill | \n| [`server/`](https://github.com/offense-research/offense/blob/main/server) ,[` shared/`](https://github.com/offense-research/offense/blob/main/shared) | API, authentication, tool contracts, job lifecycle and shared analysis | \n| [`agent/`](https://github.com/offense-research/offense/blob/main/agent) | Scanner adapters, pinned rules and container build recipes | \n| [`workers/`](https://github.com/offense-research/offense/blob/main/workers) | Cloudflare orchestration and execution boundaries; not a configured production deployment | \n| [`src/`](https://github.com/offense-research/offense/blob/main/src) ,[` site/`](https://github.com/offense-research/offense/blob/main/site) | React console, landing site and public tool directory | \n| [`scripts/`](https://github.com/offense-research/offense/blob/main/scripts) ,[` sdk/`](https://github.com/offense-research/offense/blob/main/sdk) ,[` cli/`](https://github.com/offense-research/offense/blob/main/cli) | Bootstrap/build tools, SDK and client sources | \n| [`test/`](https://github.com/offense-research/offense/blob/main/test) ,[` docs/`](https://github.com/offense-research/offense/blob/main/docs) | Synthetic regression tests, setup guides and security contracts | \n\nSome paths and schemas retain **Purple** names for compatibility. They are not\na separate product you need to install.\n\n| Guide | What it covers | \n|---|---|\n| [Local engine](https://github.com/offense-research/offense/blob/main/offense/README.md) | Dependency analysis, triage, rehearsal and optional local helpers | \n| [Agent installation](https://github.com/offense-research/offense/blob/main/offense/docs/install.md) | Project-scoped MCP configuration, skills and client coexistence | \n| [offense.sh Agent Skill](https://github.com/offense-research/offense/blob/main/.agents/skills/scanning-with-offense/SKILL.md) | Portable instructions for scoped audits, hosted-tool approval and verified remediation | \n| [Self-hosting](https://github.com/offense-research/offense/blob/main/docs/self-hosting.md) | Bootstrap, Docker isolation, operator credentials, backup and recovery | \n| [Hosted account and API](https://github.com/offense-research/offense/blob/main/docs/offense-platform.md) | Sign-in, tool discovery, quotes, jobs, usage and billing contracts | \n| [SDK](https://github.com/offense-research/offense/blob/main/sdk/README.md) | Programmatic dependency analysis and hosted-scan client interfaces | \n| [Agent-host integration](https://github.com/offense-research/offense/blob/main/docs/agent-security.md) | Explicit lifecycle checks and the difference between tools and enforced gates | \n| [Public tool directory](https://offense.sh/tools) | Tool coverage, inputs and execution-mode descriptions; not a live availability guarantee | \n| [Tool contributions](https://github.com/offense-research/offense/blob/main/docs/contributing-tools.md) | Adapter ownership, licensing, limits, fixtures and verification expectations | \n| [Security reporting](https://github.com/offense-research/offense/blob/main/SECURITY.md) | Private reports and information that must not go into public issues | \n| [Release scope](https://github.com/offense-research/offense/blob/main/docs/release-preparation.md) | Source-only boundary, provenance, verification and deferred integrations | \n\nUpdates are deliberate source updates, not an automatic background updater for the local engine. Inspect upstream changes and preserve your local modifications before updating a checkout:\n\n```\ngit status --short\ngit pull --ff-only\nnpm --prefix offense ci --ignore-scripts\n```\n\nRun the engine's checks after updating, and restart the coding-agent session so\nit loads the current skill and MCP configuration. For the platform, follow the\n[self-hosted upgrade procedure](https://github.com/offense-research/offense/blob/main/docs/self-hosting.md#acceptance-upgrades-and-recovery):\nstop the API, back up the database and encryption key together, rebuild and test,\nthen restart. A source pull alone is not a completed platform upgrade.\n\n- **Already using the hosted Offense connection?** Keep it. Add the local engine\nunder`offense-community` ; do not overwrite the hosted`offense` entry.\n- **Already using a Purple skill or CLI?** Legacy entrypoints and report schemas\nremain for compatibility. Review customized instructions before adopting the\ndocumented Offense entrypoints; do not delete unrelated client settings.\n- **Coming from another coding agent?** Keep that agent's model, tools and\nproject instructions. Add Offense as a skill/MCP capability using the client's\nsupported setup. There is no automatic import of conversations, memories,\ncredentials or model-provider settings.\n\nFrom the repository root:\n\n```\nnpm ci\nnpm run build\nnpm test\n\nnpm --prefix offense ci --ignore-scripts\nnpm --prefix offense test\nnpm --prefix offense run check\n```\n\n`npm run dev` starts Vite and the watched API for development; configure your\nlocal environment first. Default tests use synthetic fixtures and mocked\nproviders. The Docker-backed `node scripts/test-self-host.mjs` check is opt-in\nafter building the source scanner image; it exercises real local engines, not\npayments or production infrastructure.\n\nGood contributions include clearer tool coverage, reproducible positive/safe\nfixtures, scanner adapters, dependency analysis improvements and better setup\ndocumentation. Start with [CONTRIBUTING.md](https://github.com/offense-research/offense/blob/main/CONTRIBUTING.md). For tool changes,\nread the [tool contribution guide](https://github.com/offense-research/offense/blob/main/docs/contributing-tools.md) and use the\n[tool PR template](https://github.com/offense-research/offense/blob/main/.github/PULL_REQUEST_TEMPLATE/tool.md). Describe upstream\nlicenses, input limits, data flow and failure behavior—not just a tool name.\n\nThis first release is **source only**. Other scanner adapters and\ncontainer recipes, where included, are unsupported reference source in this\nself-hosted profile. The MobSF/SSLyze integrations and shared network/offline\nassessment runtimes are deferred from this export pending licensing review;\ncatalog listings and project-owned rules do not imply an included runtime.\nNo scanner images, engine binaries, package archives or downloaded datasets are\nincluded or approved for publication. Local build outputs are validation products,\nnot release artifacts. Source inclusion does not certify hosted GPL/AGPL compliance.\n\nSee the [release scope and verification record](https://github.com/offense-research/offense/blob/main/docs/release-preparation.md)\nfor the exact exclusions and the initial snapshot's provenance.\n\nIncluded Offense-owned code and the identified original artwork are licensed\nunder **Apache-2.0**. You can use, modify, fork and commercially host that code\nunder the license terms. Paid hosting is a service, not a restriction on those\nrights. The `private: true` npm flags prevent accidental package publication;\nthey do not make this source proprietary.\n\nThird-party code, fonts, rules and data retain their own licenses, and trademark\nrights remain separate. Read [LICENSE](https://github.com/offense-research/offense/blob/main/LICENSE), [NOTICE](https://github.com/offense-research/offense/blob/main/NOTICE) and\n[THIRD_PARTY_NOTICES.md](https://github.com/offense-research/offense/blob/main/THIRD_PARTY_NOTICES.md) for the boundaries and attribution.\n\n| Symptom | What to check | \n|---|---|\n| Dependency analysis cannot start | Confirm `node --version` is 24+ and install the nested package with`npm --prefix offense ci --ignore-scripts` ; root dependencies are a separate install | \n| Preview finds no supported dependency inputs | Point it at the application, not the report folder; the local engine supports npm lockfile v2/v3 and pnpm v6/v9, not every package manager or manifest-only project | \n| The agent cannot see the MCP tool | Check the absolute entrypoint, project configuration and client trust prompts; start a new session and verify tool discovery | \n| An optional scanner is missing | `doctor` checks executable availability, not installation; follow the helper's version requirements or build the supported self-hosted image | \n| Self-hosted bootstrap refuses the state directory | It intentionally refuses an existing directory or one inside the checkout; use a new external directory for a new installation, and preserve existing state for upgrades | \n| A self-hosted catalog tool is unavailable | Only dependency audits, Opengrep and Zizmor are enabled in this profile; a directory entry does not enable a runtime | \n| The web console asks you to sign in | The local operator key enables API/MCP access only; browser account features need an operator-owned GitHub OAuth app | \n| A result is partial or a provider request fails | Retain the coverage warning or error, check the stated limit/provider requirement and retry only the affected scope; do not reinterpret it as a clean scan | \n\nFor upgrades, backups, key revocation and Docker isolation, use the\n[self-hosting guide](https://github.com/offense-research/offense/blob/main/docs/self-hosting.md). For agent-specific setup, use the\n[local installation guide](https://github.com/offense-research/offense/blob/main/offense/docs/install.md).\n\n**Do I need an Offense account or an AI API key?**\nNot for local dependency analysis or the supported self-hosted profile. Your\ncoding agent uses its own model and permissions. Authenticated hosted tools use\nan Offense account; paid execution also needs credit.\n\n**Is everything in the tool directory available when I self-host?**\nNo. The catalog describes more tools than the initial self-hosted profile enables.\nSome adapters are reference source, and the deferred assessment runtimes are\nnot included. Check availability on your deployment and the release scope above.\n\n**Can I use this commercially or operate my own hosted version?**\nYes, under Apache-2.0 for the included project-owned code. Preserve required\nnotices and comply with separately licensed components. The license does not\ngrant access to Offense's infrastructure, accounts or trademarks.\n\n**Will it automatically fix and push changes?**\nNo. The dependency audit produces evidence and recommendations. Your agent can\nmake changes when authorized; rehearsal, testing, commits and publication are\nseparate actions, not side effects of an audit.\n\n**Why are some files still named Purple?**\nThey preserve existing integrations, command aliases and report schemas. Use\nthe documented Offense entrypoints for new installations.\n\n- **[Join the Discord](https://discord.gg/xP7GCnyF)** for setup questions,\nworkflow discussion and feedback on tools you would like to contribute.\n- **[Browse the open-source repository](https://github.com/offense-research/offense)** to inspect the implementation, fork it or follow development.\n- **[Open a GitHub issue](https://github.com/offense-research/offense/issues)** for\nreproducible bugs or concrete feature requests. Include the revision, runtime,\nexecution mode, expected/actual behavior and a minimal sanitized reproduction.\n- **[Contribute a tool](https://github.com/offense-research/offense/blob/main/docs/contributing-tools.md)** with its coverage, license,\ninput/data boundaries and positive/safe test evidence. Discuss substantial\nnew integrations before investing in a large implementation.\n\n**Do not post vulnerabilities, credentials, customer source or raw security\nreports in Discord or public issues.** Use\n[private vulnerability reporting](https://github.com/offense-research/offense/security/advisories/new)\nand follow [SECURITY.md](https://github.com/offense-research/offense/blob/main/SECURITY.md). Community support has no guaranteed response\ntime or security-support SLA.\n\nBuilt by **[Offense Research, Inc.](https://offenseresearch.com)** and\ncontributors. Offense integrates independently maintained security engines and\npublic advisory sources; their licenses and attribution remain in\n[THIRD_PARTY_NOTICES.md](https://github.com/offense-research/offense/blob/main/THIRD_PARTY_NOTICES.md).", "url": "https://wpnews.pro/news/show-hn-offense-security-tools-for-your-agents", "canonical_source": "https://github.com/offense-research/offense", "published_at": "2026-10-30 17:55:58+00:00", "updated_at": "2026-10-30 18:16:57.977316+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "agent-protocols", "ai-safety"], "entities": ["Offense Research, Inc.", "Offense", "Claude Code", "Codex", "Pi", "OMP", "Hermes", "Crush"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-offense-security-tools-for-your-agents", "markdown": "https://wpnews.pro/news/show-hn-offense-security-tools-for-your-agents.md", "text": "https://wpnews.pro/news/show-hn-offense-security-tools-for-your-agents.txt", "jsonld": "https://wpnews.pro/news/show-hn-offense-security-tools-for-your-agents.jsonld"}}