guardrails-profiler

Guardrails Profiler

Profile a codebase's technology stack, write .guardrails/profile.json, and upload the detected profile and default guardrail pack to SRAI using update_vibe_profile and write_default_pack.

Configured SRAI project name: <SRAI_PROJECT_NAME>

Canonical paths

• This skill & signal registry (read-only): <GUARDRAILS_SKILL_DIR>/ — e.g. .cursor/skills/guardrails-profiler, .github/skills/guardrails-profiler, .claude/skills/guardrails-profiler, or .codex/skills/guardrails-profiler for Codex depending on where this file was installed.
• Signal registry file: <GUARDRAILS_SKILL_DIR>/references/signal-registry.json
• Local guardrails file: .guardrails/profile.json

When This Runs

1. Kit init: User opted in to profile the repo and push the default pack.
2. First-run / missing profile: No .guardrails/profile.json and guardrails are needed before threat modeling.
3. Explicit re-profile: Developer asks to refresh the profile.

Quick Check: Should I Profile?

Before profiling, check if a profile already exists:

• If .guardrails/profile.json exists and has a valid schema_version: SKIP unless the developer asked to re-profile.
• If missing: PROCEED.

Profiling Procedure

Follow these steps in order.

Step 1: Locate the Project Root

The project root is the current working directory. Confirm with markers such as .git/, package.json, go.mod, etc.

Step 2: Read the Signal Registry

Read <GUARDRAILS_SKILL_DIR>/references/signal-registry.json (the copy next to this SKILL.md). Use its categories (universal, languages, frameworks, auth_identity, ai_agent, infrastructure, ci_cd, cloud_compute, databases, messaging, api_protocols, etc.) to map detected signals to guardrail pack IDs.

Step 3: Scan for Signals

Same methodology as the upstream guardrails-profiler skill:

3a. Manifest and Config File Detection

List files in the project root (1–2 levels deep). Detect manifests (package.json, pyproject.toml, go.mod, pom.xml, Dockerfile, .github/workflows/, next.config.*, etc.) per the registry.

3b. Dependency Parsing

For each manifest found, read dependencies and match names against dependency_signals in the registry. Prefer manifests over extension-only guesses.

3c. Content Signals (targeted only)

When needed, grep specific files (e.g. Terraform providers, K8s apiVersion, CloudFormation) — do not read the entire repository.

3d. File Extension Fallback

If no manifest exists for a language, use dominant extensions as a last resort.

Step 4: Assemble the Guardrails Profile Object

Build the object for .guardrails/profile.json:

{
  "schema_version": "1.0",
  "project_name": "<directory name>",
  "profiled_at": "<ISO 8601 timestamp>",
  "profiled_by": "<ide or cli id, e.g. agent, cursor-agent, claude, codex>",
  "detection_summary": {
    "languages": [],
    "frameworks": [],
    "infrastructure": [],
    "databases": [],
    "auth": [],
    "ai_agent": [],
    "ci_cd": [],
    "cloud_compute": [],
    "messaging": [],
    "api_protocols": [],
    "mobile": false
  },
  "guardrail_packs": [],
  "pack_count": 0
}

Rules for guardrail_packs:

1. Always include owasp-asvs.
2. Include owasp-masvs if mobile stacks are detected (flutter, react-native, swift, objective-c, kotlin per registry).
3. Add language, framework, auth, AI, infra, CI/CD, cloud, DB, messaging, and API packs per registry matches.
4. Deduplicate and set pack_count.

Do not invent packs or signals; if the repo is empty, use universal baseline only and empty category arrays where appropriate.

Step 5: Write .guardrails/profile.json

Create .guardrails/ if needed and write the profile file.

Step 6: Upload to SecurityReview.ai (security-review-mcp)

1. Resolve project_id: find_project_by_name with name="<SRAI_PROJECT_NAME>". If missing, follow existing kit rules (list_projects, create_project).

2. Call update_vibe_profile with project_id and arguments mapped directly from the .guardrails/profile.json object (and any required project_id fields) per the MCP tool’s documented schema. Treat the guardrails detection object as the profile payload — not a separate prose vibe document.

3. Call write_default_pack with project_id, guardrail_packs, and pack_count derived from .guardrails/profile.json (match the MCP tool’s schema).

4. MCP approval: Do not ask the user to “approve MCP” or “say you approve” for security-review-mcp. Security Review Kit passes the configured MCP server and approval settings during init-time profiling where the CLI supports it (for example Cursor CLI permissions and Copilot CLI --additional-mcp-config / --allow-all). Invoke find_project_by_name, update_vibe_profile, and write_default_pack directly. If a call still fails with permissions, report the exact CLI permission error — not a conversational approval step.

5. Confirm success: path written (.guardrails/profile.json) and whether both MCP calls succeeded, or the exact error.

Step 7: Report

Give a concise summary of detected stack, pack count, and upload status.

Empty / New Repository Handling

If there are no signals:

1. Optionally read .git/config for hints.
2. Emit minimal profile: owasp-asvs only, empty summaries where appropriate.
3. Still write .guardrails/profile.json (minimal baseline profile) and attempt MCP calls.

IDE-Specific Notes

When run from Cursor Agent CLI, GitHub Copilot CLI, Claude Code, or Codex CLI, set profiled_by to a stable id (agent or cursor-agent, copilot, claude, codex).