@boringsec/claude-code

BoringSec MCP for Claude Code.

Adds local security tooling to Claude Code with one-time device authorization, URL and repo scanning, local workspace scanning, AI remediation guidance, compliance reporting, and transparent usage visibility.

Install

Use it directly with npx:

npx -y @boringsec/claude-code login

Authentication

Preferred local flow:

1. Run npx -y @boringsec/claude-code login
2. Approve the browser link that opens automatically, or open the printed URL manually
3. Approve the short authorization code
4. The package stores a dedicated machine credential locally, preferring the OS keychain when supported

No manual API key copy is required for normal editor setup.

You can still override with:

• BORINGSEC_API_KEY
• BORINGSEC_API_URL

Bootstrap Config

Project-local setup for Claude Code and Cursor:

npx -y @boringsec/claude-code init --editor both --scope project --write-rules

That command:

• writes .mcp.json for Claude Code
• writes .cursor/mcp.json for Cursor
• creates .boringsecignore
• creates .boringsec/policy-bundle.json
• writes starter .cursorrules and AGENTS.md

Claude Code Config

Project-local config generated by init:

{
  "mcpServers": {
    "boringsec": {
      "command": "npx",
      "args": ["-y", "@boringsec/claude-code"]
    }
  }
}

CLI Commands

npx -y @boringsec/claude-code login
npx -y @boringsec/claude-code doctor
npx -y @boringsec/claude-code doctor --fix
npx -y @boringsec/claude-code init
npx -y @boringsec/claude-code review-diff --mode diff --markdown-output boringsec-review.md --sarif-output boringsec-review.sarif --github-annotations-output boringsec-review.annotations.json
npx -y @boringsec/claude-code autofix --issue-code missing-gitignore
npx -y @boringsec/claude-code rotate
npx -y @boringsec/claude-code upgrade --channel stable
npx -y @boringsec/claude-code settings --telemetry off
npx -y @boringsec/claude-code reset-history --remote
npx -y @boringsec/claude-code support-bundle --project-root . --output boringsec-support.json
npx -y @boringsec/claude-code release-notes
npx -y @boringsec/claude-code migrate-config --apply
npx -y @boringsec/claude-code cleanup --scope project --editor both --logout --revoke
npx -y @boringsec/claude-code smoke-checklist --editor both
npx -y @boringsec/claude-code status
npx -y @boringsec/claude-code logout
npx -y @boringsec/claude-code logout --revoke
npx -y @boringsec/claude-code serve

doctor --fix bootstraps missing editor config, ignore rules, workspace bundle, and starter rule files before re-running checks. logout --revoke removes the local credential and revokes the device-issued API key remotely. rotate renews a stored device credential in place and extends the expiry window without manual key copy. autofix prints a safe patch blueprint for supported findings without applying code automatically. upgrade rewrites pinned .mcp.json / .cursor/mcp.json entries to the desired stable, beta, canary, or explicit version target. settings controls telemetry, update notices, local history, retention, and the preferred release channel. reset-history clears local MCP report history and can also delete persisted server-side MCP telemetry summaries. support-bundle exports a sanitized diagnostics bundle for support without raw code, prompts, or secrets. release-notes shows compatibility policy, recommended version, and recent MCP release highlights. migrate-config upgrades editor config and .boringsec/* files to the current schema. cleanup removes editor config, workspace artifacts, and optionally stored credentials for a clean uninstall/reset path. smoke-checklist prints the final human in-app validation flow for Claude Code and Cursor after npm publish.

CI And PR Reviews

Use the local diff gate directly from CI:

npx -y @boringsec/claude-code review-diff \
  --mode diff \
  --diff-base-ref origin/main \
  --markdown-output boringsec-review.md \
  --sarif-output boringsec-review.sarif \
  --github-annotations-output boringsec-review.annotations.json

The package also ships a starter GitHub Action template at:

templates/github-actions/boringsec-review.yml

Tools

| Tool | Description | |------|-------------| | boringsec_scan | Scan a deployed URL for security vulnerabilities | | boringsec_scan_repo | Scan a public GitHub repository | | boringsec_scan_async | Start an asynchronous URL scan | | boringsec_workspace_review | Primary editor-facing project review with compact inputs and a human-readable summary | | boringsec_check | Get completed scan results by ID | | boringsec_scan_status | Poll an asynchronous scan | | boringsec_ai_analysis | Generate threat scenarios and prioritized remediation | | boringsec_compliance | Generate PCI DSS, GDPR, SOC 2, HIPAA, or ISO 27001 reports | | boringsec_fix | Load built-in and community remediation prompts | | boringsec_autofix | Generate a safe patch blueprint for supported findings | | boringsec_generate_rules | Generate .cursorrules and/or AGENTS.md | | boringsec_policy_packs | List secure coding policy packs and recommended bundles | | boringsec_workspace_rules | Generate or write workspace-managed rule files from .boringsec/policy-bundle.json | | boringsec_review_diff | Review the current diff or staged changes with a merge gate, Markdown summary, SARIF, and GitHub annotation output | | boringsec_sync_waivers | Submit .boringsec/review-waivers.json into the org-level approval queue | | boringsec_finding_feedback | Send false-positive, accepted-risk, or resolved feedback back to BoringSec | | boringsec_usage | Show tier, quota, features, and usage-based pricing |

Advanced Raw Tools

The default editor-facing MCP surface intentionally hides the low-level raw scanners that generate noisy payload previews in Claude Code and Cursor.

If you need them for CI, automation, or precision debugging, start the MCP server with:

BORINGSEC_EXPOSE_ADVANCED_TOOLS=1 npx -y @boringsec/claude-code serve

That advanced surface adds:

• boringsec_scan_workspace
• boringsec_scan_project
• boringsec_scan_code

Local Workspace Helpers

• boringsec_workspace_review supports mode: "auto" | "staged" | "diff" | "full"
• auto prefers staged files first, then changed files, then falls back to the full repo
• add a .boringsecignore file at the project root to exclude generated files, fixtures, or irrelevant paths from local MCP scans
• .boringsec/policy-bundle.json lets teams keep workspace-managed policy packs under version control
• .boringsec/policy-bundle.json can include managedTeamSlug to inherit centrally managed team governance from BoringSec
• managed team governance can now inherit an org baseline, so one central policy slug can roll out policy packs, waiver rules, and device lifecycle settings across multiple linked teams
• recommended policy packs now cover auth/session hardening, SSRF guardrails, webhook trust, and payment entitlement integrity in addition to the baseline packs
• .boringsec/review-waivers.json lets teams suppress known findings with reason, owner, approval, ticket, and optional expiry, and expired waivers reappear as review findings
• boringsec_sync_waivers pushes local waiver bundles into the central org approval queue when a repo inherits managed team governance
• boringsec_finding_feedback sends false-positive and resolution feedback back to BoringSec for triage and tuning
• boringsec_autofix gives low-risk patch blueprints for common repo hardening findings like missing .gitignore, missing SECURITY.md, unsafe Docker runtime users, and loose GitHub Actions permissions
• boringsec_workspace_rules can generate local starter rules without needing a live API call when no scanId is supplied
• boringsec_review_diff is designed for pre-merge review, CI gates, PR summaries, SARIF export, and GitHub workflow annotations
• advanced users can expose boringsec_scan_workspace for diffBaseRef, includeUntracked, and maxFiles controls by setting BORINGSEC_EXPOSE_ADVANCED_TOOLS=1

Doctor

Run a full self-check:

npx -y @boringsec/claude-code doctor
npx -y @boringsec/claude-code doctor --fix
npx -y @boringsec/claude-code doctor --json

Doctor verifies:

• authentication source
• secure credential storage backend
• Claude Code and Cursor config presence
• workspace policy bundle and rule files
• managed team governance reachability when managedTeamSlug is configured
• local review waiver validity and expired suppressions
• waiver governance quality including missing owner, approval, ticket, or non-expiring exceptions
• conflicts between local waiver files and centrally managed team waiver policy
• managed device lifecycle drift, including editor allowlists and rotate-window warnings, when the repo inherits a team policy
• API reachability, tier, and current device posture
• expiry warnings and missing default scopes on the current device key
• MCP config migrations, local history retention, and the latest local report snapshot
• backend compatibility policy, recommended package version, and the last transport failure seen by the client

Prompts And Resources

The MCP server also exposes prompt and resource helpers for richer editor workflows:

• prompt: boringsec_workspace_review
• prompt: boringsec_async_scan_followup
• resource: boringsec://docs/quickstart
• resource: boringsec://docs/scopes

Requirements

• Node.js 18+
• BoringSec Pro or higher for authenticated API access
• Business or Enterprise for async scans and compliance-heavy flows
• macOS Keychain is used automatically on macOS; Linux Secret Service is used when secret-tool is available; Windows uses a DPAPI-protected local secret blob; other environments fall back to the local config file

Release Hygiene

• scripts/mcp-claude-smoke.mjs, scripts/mcp-cursor-smoke.mjs, and scripts/mcp-review-smoke.mjs validate install, init, doctor, and review flows
• .github/workflows/publish-claude-code.yml now runs post-publish smoke against the just-published npm version, not only against the local build
• publish now supports stable / beta / canary dist-tags through workflow dispatch inputs
• .github/workflows/rollback-claude-code.yml provides a quick dist-tag rollback surface
• publishing is set up for trusted publishing via GitHub Actions OIDC instead of long-lived npm tokens

Links

• BoringSec
• MCP Docs
• API Keys