Offense

Security tools your AI agent can discover, call and verify.

Offense is a product by Offense Research, Inc.. Open-source software, optional paid hosting.

Give Pi, OMP, Hermes, Codex, Claude Code, Crush or another coding agent the tools to audit dependencies, inspect source and workflows, and test a proposed fix. Offense returns structured security evidence through CLI, MCP and HTTP. Your agent reads that evidence, investigates your code, makes authorized changes and runs your tests—with its existing model, repository access and permissions.

Open-source repository · Discord · Hosted service · Self-hosting · Contributing · Report a vulnerability

Start here: Give this to your agent · Add with a PR · Recipes · Install the CLI · Agent installation · Choose a mode · Local quick start · MCP setup · Self-hosted platform · Documentation · Troubleshooting · Community

Add Offense to your repository with a PR

Add Offense to your repo →

Enter your GitHub repository and base branch. The installer opens GitHub's prefilled workflow editor; review the file, choose Create a new branch, then open a pull request. No Offense account, API key or GitHub token is required. Offense prepares the link; you create and approve the PR on GitHub.

The starter adds free npm/pnpm dependency audits on pull requests using pinned, read-only GitHub Actions. It never installs or runs your app, edits code or calls paid Offense tools. Dependency metadata goes to OSV/npm; reports are retained as GitHub artifacts for seven days. Advisories are report-only; coverage warnings and scan errors fail the check. GitHub Actions usage limits and charges still apply. This is a dependency check, not the full tool catalog.

Review the template · Manual installation, privacy and updates

Related MCP server: GPT Commander

Give this to your agent

Paste this into your coding agent in the project you want to check:

Set up Offense for this project. Read the installation instructions at
https://github.com/offense-research/offense#install-the-offensesh-agent-skill
and review the skill at
https://raw.githubusercontent.com/offense-research/offense/main/.agents/skills/scanning-with-offense/SKILL.md

Reuse an existing reviewed Offense checkout or connection if available.
Otherwise inspect the public source before using its helpers. Install the
skill in this agent's project-local skill directory, preserving custom files
and other agent settings. Tell me if a new session or project trust is needed.

Run only the offline dependency-input preview. Show the selected lockfiles,
unsupported inputs and which execution mode would perform the real audit.
Do not upload data, run a paid scan, install the target project's dependencies,
edit application code, commit or push.

The first success is a real preview and an explicit scope, not “installed” without a command result. The agent needs terminal/filesystem access and Node; copying a skill does not give a chat-only client those capabilities. If it cannot read GitHub pages, use the raw skill URL or a reviewed local checkout.

Already configured? Ask: “Use Offense to check my app for security problems, explain the findings and consequences, and help me decide what to fix.” Offense infers relevant checks from the project, reports missing coverage, and asks only for the inputs or authorization those checks need. Assessment alone does not authorize application edits or paid calls. Narrow dependency and local-only requests keep their scope.

Start with one of the task prompts below. Prefer manual setup? Use the per-agent instructions.

Recipes from the landing page

Codex plugin

The native plugin is built from the same maintained skill and CLI in this repo. To try a local checkout with Codex:

codex plugin marketplace add /absolute/path/to/offense
codex plugin add offense@offense

Start a new Codex session, then ask $offense:offense to check your app and explain the findings. Installing does not log in, scan, buy credit or register MCP. The plugin reuses existing connections or its bundled CLI. Codex owns updates; credentials stay in the CLI's private configuration. If you already installed a manual Offense skill, choose which entry point to keep; customized skills and project instructions are never removed automatically.

Once these files are published on the repository's default branch, the intended remote registration is codex plugin marketplace add offense-research/offense, followed by codex plugin add offense@offense. The local path has been smoke tested; the remote command requires verification against that published ref. Public OpenAI directory listing is a separate submission, not part of this build.

Put the examples on offense.sh to work. Each recipe includes an agent prompt, prerequisites, commands, approval boundaries and the evidence to return. Start with a single reviewed run before adding recurring automation.

These are recipes for your agent, not installed schedules, hooks or bots. Local scanners need their pinned engines; hosted Gitleaks needs availability, upload approval and a spending ceiling. See the shared setup and limits.

What you can do

• Find vulnerable dependencies. Inventory npm/pnpm lockfiles, query OSV advisories and inspect upgrade options with the independent local engine.

• Give your agent actionable context. Produce structured findings and a repository-specific remediation prompt; use explicit triage and rehearsal commands when you need deeper evidence.

• Check source and GitHub Actions workflows. Run pinned Opengrep and Zizmor engines through the self-hosted API/MCP profile in isolated Docker containers.

• Discover tools before running them. Inspect coverage, supported inputs, availability and price quotes. A directory listing is not a promise that a tool is enabled on your deployment.

• Use the same job workflow across clients. Submit bounded jobs, retrieve results and preserve partial/failed outcomes through the CLI, MCP or HTTP API.

Offense 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.

From a finding to a reviewed fix

See From a finding to a reviewed fix.

Ask for the outcome you want

See Ask for the outcome you want.

What your agent should read and return

See What your agent should read and return.

Export a PDF report locally

See Export a PDF report locally.

Choose how to run it

The 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.

Install the CLI

See Install the CLI.

Homebrew — macOS and Linux

See Homebrew — macOS and Linux.

Stable GitHub release — Node.js 20+

See Stable GitHub release — Node.js 20+.

Ubuntu and Arch Linux

See Ubuntu and Arch Linux.

npx / npm exec — run without a global install

See npx / npm exec — run without a global install.

npm — install the command globally

See npm — install the command globally.

pnpm or Bun — one-off execution

See pnpm or Bun — one-off execution.

From a reviewed checkout — no package manager install

See From a reviewed checkout — no package manager install.

After installation

See After installation.

Quick start: local dependency analysis

Use Node.js 24 or newer, npm and Git. This path does not start a server, install Docker scanners or require an account.

git clone https://github.com/offense-research/offense.git
cd offense
npm --prefix offense ci --ignore-scripts

# Inspect the runtime and preview supported dependency inputs without network calls.
node offense/bin/offense.mjs doctor /absolute/path/to/your-project
node offense/bin/offense.mjs scan /absolute/path/to/your-project --preview

When you are ready to query OSV/npm and write a report:

node offense/bin/offense.mjs scan /absolute/path/to/your-project \
  --output /absolute/path/outside-your-project/offense-report

The scan writes scan.json for structured evidence and remediation.md for your agent. It does not edit the target project, install its dependencies, execute its scripts or open a pull request. Review reports before sharing them; they can contain private package names and local paths.

The top-level repository and the nested offense/ package have separate dependency installations. The commands above install only the local engine. See the local-engine README for triage, upgrade rehearsal and optional scanner helpers, each with its own prerequisites.

Local CLI reference

Run these from the repository root, replacing PROJECT with your target's path:

Read both findings and coverage. scan.json contains machine-readable analysis; remediation.md gives your agent the evidence and next checks. A proposed upgrade still needs compatibility tests. Zero returned findings apply only to the checked scope and available advisory data—not every dependency, code path or future vulnerability.

Connect your coding agent

See Connect your coding agent.

Install the offense.sh Agent Skill

See Install the offense.sh Agent Skill.

Hermes Agent — native skill installation

See Hermes Agent — native skill installation.

Choose your agent

See Choose your agent.

Copy the skill without replacing custom instructions

See Copy the skill without replacing custom instructions.

Make the existing helpers available

See Make the existing helpers available.

Run the self-hosted platform

The initial profile runs the Node API and console with SQLite, a local operator API key and isolated Docker scanners. It supports dependency advisory analysis, Opengrep 1.32.0 and Zizmor 1.31.1. Other catalog tools remain disabled.

Self-hosting has no Offense billing. The bootstrap disables both scanner credit and hosted model billing automatically—no subscription, prepaid balance or payment credentials required. You cover your own infrastructure costs.

From the repository root on your own Linux amd64 machine:

npm ci
npm run build
docker build -f agent/source.Dockerfile -t offense-source:local .
node scripts/init-self-host.mjs "$HOME/offense-state"
node --env-file="$HOME/offense-state/server.env" server/index.js

The bootstrap creates a new private state directory outside the checkout and refuses to overwrite an existing installation. It stores the API key, encryption key and database there without printing credentials. The server binds to loopback on port 3217; it is not an Internet-ready multi-tenant setup.

Already configured? Keep these values in your private server.env and restart the API after changes; do not recreate the state directory:

OFFENSE_SELF_HOSTED=true
SCAN_BILLING_ENABLED=false
WHOP_BILLING_ENABLED=false

Point your client at your own OFFENSE_API_URL, not https://offense.sh. The billing-off checklist shows how to verify zero-priced quotes and resolve inherited environment conflicts. Use --max-price 0 when submitting CLI calls to retain a zero-cost ceiling.

Follow the self-hosting guide to load the operator key, configure CLI/API/MCP access, back up state and run acceptance checks. Allow at least 2 GiB RAM per scanner plus memory for the API. Docker access is effectively host-administrator access: use a dedicated environment and never expose the Docker socket to clients.

The operator key is for API/MCP access, not browser login. Browser account features require your own GitHub OAuth setup. Review the guide's reverse-proxy, credential and isolation requirements before exposing the service beyond loopback.

Use the hosted service

Hosted Offense operates the infrastructure and charges for enabled hosted execution. From a checkout with root dependencies installed:

node scripts/offense-cli.mjs login
node scripts/offense-cli.mjs tools
node scripts/offense-cli.mjs balance

The hosted agent setup and account/API guide cover client configuration and the quote → submit → result workflow. Discovery and quotes do not themselves run a paid scan. Review the input, target authorization and maximum charge before submitting; paid calls require credit and explicit spending approval.

You can use the local engine without logging into the hosted service. Its MCP configuration uses offense-community, while the optional hosted client uses offense, so the two can coexist.

CLI, MCP and HTTP at a glance

Choose the interface that fits your workflow, not a different set of security claims. The local engine is separate from the platform API:

For local port exposure, select one literal IP and up to 256 TCP ports. Review the preview, then add --run --confirm-active-testing only with permission. An optional --expected-ports allowlist flags unexpected reachability without claiming exploitability; timeouts remain unknown. Results describe your current network vantage point, not necessarily public internet exposure.

Platform MCP uses the configured server's /mcp endpoint and appropriate authentication. Never paste tokens into a chat, commit them to MCP configuration or substitute another connector's credentials. Self-hosted billing is disabled; hosted quotes and account access depend on the selected account and deployment.

For application-controlled checks, the SDK guide and agent integration guide describe explicit lifecycle hooks. Making a tool available through MCP does not force an agent to call it, and configuring a policy does not automatically install a deployment hook.

Data and security boundaries

Self-hosted source scanner jobs have no network access, host mounts or Docker socket. They run as an unprivileged user with a read-only filesystem and bounded resources. Submitted code is scanned, not executed. Optional rehearsal and API testing helpers do execute code when explicitly invoked; use disposable environments and review their separate contracts.

These controls do not eliminate kernel, scanner or configuration risk. Keep engines current, protect operator credentials and scan only authorized targets. Report vulnerabilities through private security reporting, not public issues containing source, credentials or raw scan reports.

Repository guide

For maintained sources and generated copies, see Find the owning files.

Some paths and schemas retain Purple names for compatibility. They are not a separate product you need to install.

Documentation

Updating and moving from an existing setup

Updates 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:

git status --short
git pull --ff-only
npm --prefix offense ci --ignore-scripts

Run the engine's checks after updating, and restart the coding-agent session so it loads the current skill and MCP configuration. For the platform, follow the self-hosted upgrade procedure: stop the API, back up the database and encryption key together, rebuild and test, then restart. A source pull alone is not a completed platform upgrade.

• Already using the hosted Offense connection? Keep it. Add the local engine under offense-community; do not overwrite the hosted offense entry.

• Already using a Purple skill or CLI? Legacy entrypoints and report schemas remain for compatibility. Review customized instructions before adopting the documented Offense entrypoints; do not delete unrelated client settings.

• Coming from another coding agent? Keep that agent's model, tools and project instructions. Add Offense as a skill/MCP capability using the client's supported setup. There is no automatic import of conversations, memories, credentials or model-provider settings.

Offense in its own CI

The dependency agent example provides secret-free PR audits and opt-in, isolated Hermes repairs with independent verification and draft PR delivery. Forks configure their own model key; no Offense account or production credentials are required.

Develop and contribute

From the repository root:

npm ci
npm run build
npm test

npm --prefix offense ci --ignore-scripts
npm --prefix offense test
npm --prefix offense run check

npm run dev starts Vite and the watched API for development; configure your local environment first. Default tests use synthetic fixtures and mocked providers. The Docker-backed node scripts/test-self-host.mjs check is opt-in after building the source scanner image; it exercises real local engines, not payments or production infrastructure.

Good contributions include clearer tool coverage, reproducible positive/safe fixtures, scanner adapters, dependency analysis improvements and better setup documentation. Start with CONTRIBUTING.md. For tool changes, read the tool contribution guide and use the tool PR template. Describe upstream licenses, input limits, data flow and failure behavior—not just a tool name.

Current release scope

This first release is source only. Other scanner adapters and container recipes, where included, are unsupported reference source in this self-hosted profile. The MobSF/SSLyze integrations and shared network/offline assessment runtimes are deferred from this export pending licensing review; catalog listings and project-owned rules do not imply an included runtime. No scanner images, engine binaries, package archives or downloaded datasets are included or approved for publication. Local build outputs are validation products, not release artifacts. Source inclusion does not certify hosted GPL/AGPL compliance.

See the release scope and verification record for the exact exclusions and the initial snapshot's provenance.

License

Included Offense-owned code and the identified original artwork are licensed under Apache-2.0. You can use, modify, fork and commercially host that code under the license terms. Paid hosting is a service, not a restriction on those rights. The private: true npm flags prevent accidental package publication; they do not make this source proprietary.

Third-party code, fonts, rules and data retain their own licenses, and trademark rights remain separate. Read LICENSE, NOTICE and THIRD_PARTY_NOTICES.md for the boundaries and attribution.

Troubleshooting

For upgrades, backups, key revocation and Docker isolation, use the self-hosting guide. For agent-specific setup, use the local installation guide.

Frequently asked questions

Do I need an Offense account or an AI API key? Not for local dependency analysis or the supported self-hosted profile. Your coding agent uses its own model and permissions. Authenticated hosted tools use an Offense account; paid execution also needs credit.

Is everything in the tool directory available when I self-host? No. The catalog describes more tools than the initial self-hosted profile enables. Some adapters are reference source, and the deferred assessment runtimes are not included. Check availability on your deployment and the release scope above.

Can I use this commercially or operate my own hosted version? Yes, under Apache-2.0 for the included project-owned code. Preserve required notices and comply with separately licensed components. The license does not grant access to Offense's infrastructure, accounts or trademarks.

Will it automatically fix and push changes? No. The dependency audit produces evidence and recommendations. Your agent can make changes when authorized; rehearsal, testing, commits and publication are separate actions, not side effects of an audit.

Why are some files still named Purple? They preserve existing integrations, command aliases and report schemas. Use the documented Offense entrypoints for new installations.

Community and support

• Join the Discord for setup questions, workflow discussion and feedback on tools you would like to contribute.

• Browse the open-source repository to inspect the implementation, fork it or follow development.

• Open a GitHub issue for reproducible bugs or concrete feature requests. Include the revision, runtime, execution mode, expected/actual behavior and a minimal sanitized reproduction.

• Contribute a tool with its coverage, license, input/data boundaries and positive/safe test evidence. Discuss substantial new integrations before investing in a large implementation.

Do not post vulnerabilities, credentials, customer source or raw security reports in Discord or public issues. Use private vulnerability reporting and follow SECURITY.md. Community support has no guaranteed response time or security-support SLA.

Built by Offense Research, Inc. and contributors. Offense integrates independently maintained security engines and public advisory sources; their licenses and attribution remain in THIRD_PARTY_NOTICES.md.