Skip to content

Incident Response Procedures — V025-claude-toolkit

Response procedures for security incidents affecting the VisiTrans Claude Toolkit. Each incident type follows the standard lifecycle: Detect → Contain → Eradicate → Recover → Learn.

1. Compromised npm Package

Detect

  • setup.sh --verify reports integrity mismatch for an MCP package
  • npm audit flags a known vulnerability in an installed package
  • Security advisory published for a pinned dependency

Contain

  1. Stop all Claude Code sessions using the affected MCP server
  2. Remove the MCP server: claude mcp remove <server-name>
  3. Clear npm cache for the affected package: npm cache clean --force

Eradicate

  1. Identify the compromised version in configs/security/mcp-package-hashes.yaml
  2. Check npm advisory for the vulnerability details and affected version range
  3. If the package has a safe version: update the pin in setup.sh and hash manifest
  4. If no safe version exists: remove the MCP server from setup.sh entirely

Recover

  1. Install the verified safe version: run setup.sh --full
  2. Verify integrity: run setup.sh --verify
  3. Review recent agent sessions for any suspicious tool calls or file modifications
  4. Run /repo-audit to verify no files were tampered with

Learn

  1. Document the incident in a session journal entry: /vt-c-journal "Incident: compromised npm package [name]"
  2. If the vulnerability was not caught by existing controls, create a SPEC to add detection
  3. Update configs/security/mcp-package-hashes.yaml with the new safe version

2. Secret Leaked to External Service

Detect

  • Secret scanner hook blocks a write containing a credential pattern
  • capture_thought sends content that should have been sanitized
  • Git pre-commit hook catches a staged secret
  • Manual discovery of credentials in logs, thoughts, or committed files

Contain

  1. Immediately revoke the leaked credential (API key, token, password)
  2. If leaked via capture_thought: purge the thought from Open Brain if possible
  3. If committed to git: do NOT force-push yet — first assess the blast radius

Eradicate

  1. Rotate all credentials that may have been exposed
  2. If the secret was committed:
  3. Create a new commit removing the secret
  4. Add the file pattern to .gitignore if applicable
  5. Consider using git filter-branch or BFG Repo-Cleaner if the secret was pushed to a remote
  6. Update environment variables with new credential values

Recover

  1. Verify new credentials work: test affected integrations
  2. Run setup.sh --verify to confirm no secrets remain in tracked files
  3. Run /repo-audit to scan for any remaining credential patterns
  4. Monitor service logs for unauthorized access using the leaked credential

Learn

  1. Document: /vt-c-journal "Incident: secret leaked via [channel]"
  2. If the leak bypassed the secret scanner: update scanner regex patterns
  3. If the leak was via capture_thought: strengthen sanitization rules in CLAUDE.md 10a
  4. Create an intake proposal if a new control is needed

3. Malicious Article/Proposal Injected

Detect

  • /inbox-qualify encounters malformed YAML or suspicious content
  • Proposal contains unexpected target_skill not in manifest
  • Slug contains path traversal characters after sanitization should have removed them
  • Review identifies a routed article containing prompt injection attempts

Contain

  1. Do NOT process the suspicious file further
  2. Move the file to a quarantine location: intake/archive/quarantine/
  3. If the file was already routed: check the destination for any files created by the injection

Eradicate

  1. Remove the malicious file from all locations (inbox, knowledge, pending)
  2. If a proposal was generated from the malicious content: delete the proposal
  3. Review intake/knowledge/ for any files created or modified around the same time
  4. Check git history for any unusual commits: git log --oneline --since="2 hours ago"

Recover

  1. Re-run /inbox-qualify on remaining inbox items
  2. Verify knowledge index integrity: check intake/knowledge/index.json for unexpected entries
  3. Run /repo-audit to verify no files were placed outside expected directories

Learn

  1. Document: /vt-c-journal "Incident: malicious article in intake pipeline"
  2. If the injection bypassed validation: strengthen the validation rules in /inbox-qualify
  3. Create an intake proposal for any new sanitization patterns needed
  4. Consider adding content-based heuristics for detecting injection attempts

4. Hook Checksum Mismatch

Detect

  • /repo-audit reports hook checksum differs from configs/security/trusted-hooks.yaml
  • Manual inspection reveals unexpected hook content
  • Hook behavior changes without a corresponding commit

Contain

  1. Stop all Claude Code sessions in the affected project
  2. Do NOT run any commands that would trigger the suspect hook
  3. Identify which hook file has been modified

Eradicate

  1. Compare the modified hook with the expected version: 
    diff ~/.claude/hooks/<hook-name> <expected-source-path>
  2. If the modification is unauthorized: restore from the toolkit repository
  3. If the modification is legitimate (new feature): update trusted-hooks.yaml with new checksum

Recover

  1. Restore hooks: run setup.sh --full to reinstall all hooks from source
  2. Verify integrity: run setup.sh --verify and /repo-audit
  3. Review recent session activity for any actions taken while the compromised hook was active

Learn

  1. Document: /vt-c-journal "Incident: hook checksum mismatch for [hook-name]"
  2. If the modification was unauthorized: investigate how the hook was modified
  3. Consider enabling allowManagedHooksOnly: true if not already set
  4. Evaluate whether a session-start hook verification step is warranted

5. Unauthorized MCP Server

Detect

  • claude mcp list shows an MCP server not in the governed list (azure-devops, taskmaster-ai, github, plugin-provided)
  • /repo-health flags an unknown MCP server
  • Manual discovery of unexpected server in ~/.claude.json

Contain

  1. Remove the unauthorized server immediately: claude mcp remove <server-name>
  2. Do NOT interact with the server before removal
  3. Note the server configuration (name, transport, command, args) for investigation

Eradicate

  1. Check ~/.claude.json for any remaining references to the unauthorized server
  2. Verify no project-level .mcp.json files reference the server
  3. If the server was installed via npm: uninstall and clear cache 
    npm uninstall -g <package-name>
npm cache clean --force

Recover

  1. Run setup.sh --verify to confirm only governed servers are configured
  2. Review recent sessions for any tool calls made via the unauthorized server
  3. If the server had stdio transport: check for any files created by the server process

Learn

  1. Document: /vt-c-journal "Incident: unauthorized MCP server [name] discovered"
  2. If the server was added without team knowledge: review who has access to modify MCP configuration
  3. Consider enforcing enableAllProjectMcpServers: false in managed settings
  4. Create an intake proposal if MCP server governance controls need strengthening

General Principles

  1. Evidence first: Before taking destructive actions, capture screenshots, log output, and file contents
  2. Least disruption: Contain the threat without destroying evidence or disrupting unaffected systems
  3. Communication: Inform the team immediately for any P0 (credential leak, compromised package) incident
  4. Documentation: Every incident results in a journal entry and, if appropriate, a SPEC for improved controls
  5. No blame: Focus on systemic improvements, not individual mistakes