securityreviewai/securityreview-kit

1. What this repo is

- This is a Node.js CLI package that bootstraps the SRAI security-review MCP setup into a workspace.

- Its job is not to run the security review itself, but to install IDE/CLI-specific configuration so assistants like Cursor, Claude Code, VS Code Copilot, Windsurf, Codex, Gemini CLI, and Antigravity consult security guidance before code generation.

2. Top-level architecture

- The executable entrypoint is bin/securityreview-kit.js, which hands control to src/cli.js.

- src/cli.js dispatches into three user-facing commands: init, status, and switch-project.

- The rest of the code is split into two main subsystems:

- Generators: create target-specific MCP configs, rules, skills, hooks, and command files.

- Utilities: filesystem, detection, install, and profiling helpers.

3. Primary workflow: init

- src/commands/init.js is the orchestration layer.

- It gathers target selection, SRAI API settings, and optional profiling flags, then coordinates installation of:

- MCP server config for the selected target(s)

- Workspace rules and supporting files

- The install is designed to be idempotent: it updates existing workspace files rather than duplicating content.

4. Project selection and SRAI API integration

- When MCP setup is enabled, the tool fetches available projects from the SRAI platform using GET /api/projects/ with a bearer token.

- The selected project name is injected into installed rule content so the IDE/CLI instructions are tied to one SRAI project.

- This data flow matters architecturally: SRAI API → interactive project selection → generated workspace instructions.

5. Target-specific generation

- The src/generators/mcp/ directory contains adapters for each supported tool: claude, codex, cursor, gemini, vscode, and windsurf.

- These generators produce the target’s MCP configuration file in its expected location, for example:

- .cursor/mcp.json

- .mcp.json

- .vscode/mcp.json

- .windsurf/mcp_config.json

- .codex/config.toml

- .gemini/settings.json

- The key architectural boundary is that each target gets its own config format and path, but they all point to the same underlying security-review-mcp launch model.

6. Workspace rules and assistant instructions

- src/generators/rules/ contains target-specific rule emitters and shared content.

- These write the assistant-facing guidance files into tool-specific locations such as:

- .cursor/rules/...

- .claude/CLAUDE.md

- .github/copilot-instructions.md

- .windsurf/rules/...

- .codex/AGENTS.md

- GEMINI.md

- .agents/rules/...

- Shared content lives in content.md and related templates, so the repository can reuse the same security policy narrative across different assistant ecosystems.

7. Supporting assets: skills, commands, and hooks

- The repo doesn’t only install a single rule file; it also lays down auxiliary assets that shape assistant behavior.

- Examples include:

- Threat modelling skills under multiple tool-specific skill folders

- guardrails-init-profile.md command content

- hooks.json / session-policy files for tools that support hooks

- These files form a second layer of enforcement around the main rule text, helping assistants follow the same security workflow consistently.

8. Status and project switching

- src/commands/status.js inspects the current workspace and reports which target configurations are present.

- src/commands/switch-project.js reuses the installed configuration but updates the mapped workspace rules to point to a different SRAI project.

- This is a separate operational path from initial install: status is read-only, while switch-project is a targeted update of existing generated files.

9. Profiling and guardrails subsystem

- The repo includes a profiling flow for generating or refining guardrails using bundled skills under src/generators/rules/guardrails-profiler and guardrails-selection.

- src/utils/guardrails-profiler-bundle.js and src/utils/profiler-agent.js support running these profiler workflows.

- The init command can optionally trigger profiling after setup, and it has target-specific login helpers for Claude, GitHub Copilot, and Codex.

- Architecturally, this is an optional post-install pipeline that feeds on the installed workspace state.

10. Cross-cutting utilities and boundaries

- src/utils/fs-helpers.js, detect.js, constants.js, and ide-cli-install.js handle filesystem writes, environment/tool detection, and installation mechanics.

- cursor-agent-path.js and cursor-cli-permissions.js reflect tool-specific constraints for Cursor.

- src/utils/srai.js centralizes SRAI-specific network or project-related behavior.

- The repo’s boundary is clear: it reads and writes local workspace files, talks to the SRAI API when needed, and configures external IDE/CLI assistants to launch security-review-mcp via npx.

11. How to think about the system diagram

- Put the CLI at the center, with three command flows branching out: initial install, status inspection, and project switching.

- On one side, show target-specific generators writing into workspace locations.

- On another, show the SRAI API as the source of project metadata used to parameterize rules.

- If included, show the profiling subsystem as an optional downstream path that consumes the installed setup and produces guardrail/profile artifacts.