@securityreviewai/securityreview-kit 0.1.49 → 0.1.51

package/templates/shared/guardrails-selection.md

@@ -0,0 +1,185 @@
+---
+name: guardrails-selection
+description: Analyze the developer request, infer the security categories and likely threats involved, shortlist the most relevant project guardrails, then preserve the exact returned guardrail records before implementation. Use for every security-relevant code task before code is written and preserve the shortlist for the final VibeReview sync.
+---
+
+# Guardrails Selection
+
+Configured SRAI project name: `<SRAI_PROJECT_NAME>`
+
+Use this skill whenever code will be created or modified and the task has any security surface.
+
+This skill is a hard pre-write gate. Do not write, edit, patch, or generate implementation code until this skill has produced the active guardrail shortlist and the PWNISMS skill has used that shortlist for threat modelling.
+
+This skill exists to stop the IDE from treating the full `get_guardrails` result as an unstructured blob. The workflow is:
+
+1. Understand the request deeply.
+2. Infer which security categories are in play.
+3. Predict the threats that might occur for this exact task.
+4. Shortlist only the guardrails that mitigate those threats.
+5. Preserve the exact shortlisted guardrails returned by the project guardrail bundle.
+6. Carry that same shortlist forward into implementation and the final VibeReview markdown sync.
+
+Do not skip the analysis step. Do not rely on title-matching alone. Do not dump every guardrail into the final answer.
+
+## Inputs You Must Analyze First
+
+Before calling `get_guardrails`, extract the actual development intent from the prompt and surrounding code:
+
+- What is being built, changed, fixed, or refactored?
+- Which components are affected: API, UI, background jobs, auth flow, webhook, file upload, admin tooling, AI agent flow, infra code, data pipeline?
+- Which trust boundaries are crossed?
+- Which sensitive assets are touched: tokens, credentials, sessions, PII, tenancy boundaries, audit logs, secrets, internal APIs, signed URLs, payment state, workflow approvals?
+- Which technologies and patterns are involved in the existing code?
+- What abuse cases are plausible if this change is implemented poorly?
+
+You are not only selecting guardrails for the obvious functionality. You are selecting guardrails for the threats that might materialize around that functionality.
+
+## Category Inference Workflow
+
+Derive a category set for the task before shortlisting guardrails. Common categories include:
+
+- `authentication`
+- `authorization`
+- `session_management`
+- `input_validation`
+- `output_encoding`
+- `secrets`
+- `cryptography`
+- `logging`
+- `monitoring`
+- `file_uploads`
+- `deserialization`
+- `data_access`
+- `rate_limiting`
+- `network`
+- `client_side`
+- `business_logic`
+- `tenant_isolation`
+- `admin_workflows`
+
+Use both the user request and the codebase patterns to infer the category set. A task can involve multiple categories even if the prompt mentions only one feature.
+
+Examples:
+
+- “Add magic-link login” likely involves `authentication`, `session_management`, `cryptography`, `logging`, `rate_limiting`, and `client_side`.
+- “Add org admin API to update member roles” likely involves `authorization`, `tenant_isolation`, `logging`, `business_logic`, and `data_access`.
+- “Add CSV import” likely involves `input_validation`, `file_uploads`, `data_access`, `deserialization`, `logging`, and denial-of-service protections.
+- “Add client-side token refresh” likely involves `authentication`, `session_management`, `client_side`, `logging`, and `cryptography`.
+
+## Threat Mapping Requirement
+
+After identifying categories, infer the threat families that might occur. Use the reference file at `{{GUARDRAILS_SELECTION_SKILL_DIR}}/references/category-threat-map.md` every time you need to reason about category-to-threat mapping.
+
+Your goal is not to enumerate every possible weakness. Your goal is to pick the threats that should influence guardrail selection for this task.
+
+At minimum, consider whether the task can create:
+
+- authentication bypass
+- authorization bypass
+- privilege escalation
+- information disclosure
+- repudiation gaps
+- denial of service
+- unsafe client-side trust
+- insecure logging or audit gaps
+- injection-triggered security failures
+- serialization-triggered security failures
+- business-logic-triggered bypasses
+
+The shortlist should be threat-led, not catalog-led.
+
+## Guardrail Selection Procedure
+
+### Step 1: Resolve the project and load the catalog
+
+1. Call `find_project_by_name` with `name="<SRAI_PROJECT_NAME>"` to obtain `project_id`.
+2. Call `get_guardrails` with `project_id`.
+
+Treat `get_guardrails` as the broad project catalog. Do not treat the whole catalog as the final set of instructions. The returned entries are already the authoritative guardrail records for this project; shortlist from those exact records and preserve their ids, titles, rule types, categories, and instructions.
+
+Assume each returned guardrail includes the fields needed for selection, including a stable identifier for follow-up retrieval, plus:
+
+- `title`
+- `rule_type`
+- `category`
+- `instruction`
+
+If an identifier is absent, fall back to the best available stable reference exposed by the tool, but prefer the real guardrail id whenever available.
+
+### Step 2: Build a shortlist
+
+Shortlist guardrails using all of the following:
+
+- direct category match with the task
+- mitigation value against the likely threats you inferred
+- relevance to the technologies and code paths being touched
+- support for adjacent controls that prevent bypass chains
+- duplication removal
+
+Do not select a guardrail only because it sounds generally useful. Select it because it materially constrains the risky part of the current task.
+
+Examples:
+
+- If the task touches login, token issuance, password reset, session refresh, or identity proofing, prioritize authentication, session, crypto, logging, and brute-force defense guardrails.
+- If the task changes role checks, tenant scoping, admin APIs, resource ownership, or query filters, prioritize authorization, tenant isolation, data access, business-logic, and audit guardrails.
+- If the task introduces parsing, uploads, template expansion, or object hydration, prioritize input validation, file handling, deserialization, and denial-of-service guardrails.
+- If the task moves security decisions into the browser or mobile client, prioritize client-side trust, token storage, server-side revalidation, and privilege-boundary guardrails.
+
+### Step 3: Preserve exact shortlisted guardrails
+
+For every shortlisted existing guardrail, preserve the exact guardrail record returned by `get_guardrails`.
+
+Implementation must be driven by that exact shortlist, not by vague memory from the broad catalog listing. Do not re-query guardrails after implementation starts unless the shortlist is missing or the task scope materially changes.
+
+### Step 4: Track the active shortlist in context
+
+Maintain an explicit in-context list of the shortlisted existing guardrails that will govern the task. For each shortlisted existing guardrail, keep:
+
+- `id`
+- `title`
+- `rule_type`
+- `category`
+- `instruction`
+- `why_selected`
+
+Also track any new guardrails created during the task as `ide_generated`.
+
+This shortlist is the source of truth for the rest of the session.
+
+## Implementation Rules
+
+Once the exact shortlist is preserved:
+
+- Every applicable `must` guardrail is mandatory.
+- Every applicable `must_not` guardrail is a hard prohibition.
+- If two shortlisted guardrails appear to conflict, explain the conflict and resolve it before coding.
+- If the task reveals a real gap not covered by the shortlisted existing guardrails, create an `ide_generated` guardrail and apply it immediately.
+
+When deciding whether a guardrail applies, prefer security-preserving inclusion over risky omission. If it plausibly mitigates a realistic path to abuse for the current task, keep it in scope.
+
+## VibeReview Sync Contract
+
+The final sync step must reuse the shortlist from this skill. It must not call `get_guardrails` again unless the task scope materially changed.
+
+Before `sync_ai_ide_markdown` is called, ensure the main agent context clearly contains:
+
+- the exact existing guardrails shortlisted earlier
+- which of them were applied
+- whether each one was satisfied
+- any notes about partial compliance, conflicts, or rationale
+- every `ide_generated` guardrail created during the task
+
+If a guardrail was shortlisted but not fully satisfied, still include it in the handoff with `satisfied: false` and a note. Do not silently drop it.
+
+## Selection Quality Bar
+
+A good selection does all of the following:
+
+- covers the feature’s real threat surface, not just its visible functionality
+- captures adjacent controls that stop bypass chains
+- avoids irrelevant noise
+- produces a small, defensible set of guardrails that can actually guide implementation
+- leaves the final VibeReview markdown with an exact list of what the IDE selected and enforced
+
+If your shortlist feels generic, it is probably incomplete or over-broad. Re-check the prompt, the code patterns, and the threat map.

package/templates/shared/threat-modelling.md

@@ -0,0 +1,259 @@
+---
+name: PWNISMS Threat Modelling
+description: Security-first threat modelling workflow for code and architecture tasks. Walks all 7 PWNISMS categories, enforces vibe guardrails (secure by code), and synchronizes findings via a direct VibeReview markdown sync. Use after guardrail selection and before implementation.
+---
+
+# PWNISMS — Security-First Threat Modelling
+
+For EVERY security-relevant task (feature, bug fix, refactor, infra change, architecture design), run a threat model with PWNISMS.
+
+- This is a pre-implementation gate. Do not write, edit, patch, or generate implementation code until guardrail selection has completed and this PWNISMS pass has been completed.
+- Walk through all 7 categories explicitly.
+- If a category is not applicable, state it briefly and move on.
+- Anchor analysis to linked files, diffs, PRs, API specs, and diagrams whenever available.
+- Focus on realistic threats for the current context, not exhaustive attack catalogs.
+
+---
+
+## Phase 0 — Guardrail Context
+
+Before deep analysis, ensure the project-specific guardrail shortlist exists:
+
+1. Use `{{GUARDRAILS_SELECTION_SKILL_DIR}}/SKILL.md`.
+2. Resolve the project with `find_project_by_name` using `name="<SRAI_PROJECT_NAME>"`.
+3. Call `get_guardrails`, shortlist intentionally for this task, then preserve the exact returned guardrail records in context.
+4. Keep the shortlisted existing guardrails in context for implementation and the final VibeReview markdown sync.
+
+Do not perform project-profile exploration as part of PWNISMS. The old profile tools are not part of this workflow. Ground the threat model in the user request, repository code, diffs, architecture docs the user provides, and the shortlisted guardrails.
+
+If SRAI is not available, proceed with the user-provided context and repository evidence, then clearly note that project guardrails could not be fetched.
+
+---
+
+## Phase 1 — Inputs to Gather
+
+Collect these quickly before deep analysis:
+
+- **Scope**: What is changing (feature, component, service, migration, PR)?
+- **Assets**: What must be protected (PII, credentials, tokens, configs, accounts, workflows)?
+- **Entry points**: How data enters/leaves (HTTP, queues, schedulers, CLI, webhooks, integrations)?
+- **Trust boundaries**: Where data crosses users/services/networks/privilege levels?
+- **Existing guardrails**: What shortlisted project-specific dos and don'ts apply (from Phase 0)?
+
+If the user provided specific code, diffs, or architecture artifacts, prioritize those as primary evidence.
+
+---
+
+## Phase 2 — Lightweight Workflow (PWNISMS)
+
+1. **Clarify scope and assumptions**
+   - Define the exact unit of analysis.
+   - State assumptions explicitly (auth model, deployment boundary, tenant model, etc.).
+
+2. **Map assets and flows**
+   - List high-value assets and critical data paths.
+   - List entry points and exits across trust boundaries.
+   - Note which assets are covered by existing guardrails and which are not.
+
+3. **Walk all 7 PWNISMS categories**
+   - Identify plausible threats for each category.
+   - Keep findings concrete and contextual.
+   - For each threat, check if an existing guardrail already addresses it.
+
+4. **Prioritize**
+   - Select the top 3-7 risks by impact and likelihood.
+   - Factor in existing mitigations from the codebase, user-provided context, and guardrails.
+
+5. **Mitigate**
+   - Propose concrete, implementable controls for each prioritized risk.
+   - Map mitigations to specific guardrails where applicable.
+   - If a mitigation represents a recurring pattern, propose it as a new guardrail candidate.
+
+6. **Summarize residual risk**
+   - Call out remaining risk, trade-offs, and follow-up actions.
+   - Call out unknowns instead of silently guessing.
+   - Note guardrail gaps — security patterns not yet captured by any guardrail.
+
+---
+
+## The 7 Categories (What to Check)
+
+### P — Product
+
+Application and business-logic threats:
+
+- Input validation, injection, insecure deserialization.
+- Authorization gaps, privilege escalation, IDOR/BOLA.
+- Business logic abuse, replay/race conditions, unsafe redirects.
+- Error handling that leaks internals.
+- **Guardrail check:** Are there `must` / `must_not` rules for input validation, authorization patterns, error handling?
+
+### W — Workload
+
+Compute and infrastructure threats:
+
+- Insecure container/runtime posture, over-privileged workload identity.
+- Weak host/orchestrator controls and segmentation.
+- Insecure data storage/backups and DB configuration.
+- Queue/broker abuse and poison-message handling gaps.
+- **Guardrail check:** Are there rules for container security, data-at-rest encryption, workload identity?
+
+### N — Network
+
+Network and transport threats:
+
+- Missing/weak TLS, insecure service-to-service communication.
+- Exposed ports/endpoints and permissive ingress/egress.
+- Weak segmentation or lateral movement paths.
+- API-layer abuse controls missing (rate limits, request limits, CORS hardening).
+- **Guardrail check:** Are there rules for TLS enforcement, CORS policy, rate limiting?
+
+### I — IAM (Identity & Access Management)
+
+Identity and authorization threats:
+
+- Broken authentication controls and token validation.
+- Missing least-privilege RBAC/ABAC.
+- Service-to-service auth gaps.
+- Escalation paths across users, roles, or services.
+- **Guardrail check:** Are there rules for auth mechanisms, session management, privilege boundaries?
+
+### S — Secrets
+
+Credential and key management threats:
+
+- Secrets in code, images, logs, CI output, or defaults.
+- Weak rotation, revocation, or token lifetime policies.
+- Over-shared secrets across components.
+- Missing secret manager/KMS controls.
+- **Guardrail check:** Are there `must_not` rules against hardcoded secrets, `must` rules for secret manager usage?
+
+### M — Monitoring (Logging & Observability)
+
+Detection and auditability threats:
+
+- Missing logs for auth, authorization, admin/data access events.
+- Sensitive data leakage in logs.
+- Missing alerts for abuse indicators.
+- Incomplete audit trails or weak log integrity.
+- **Guardrail check:** Are there rules for what must be logged and what must not appear in logs?
+
+### S — Supply Chain
+
+Dependency and delivery threats:
+
+- Unpinned/unverified dependencies and vulnerable packages.
+- Third-party integration trust and scope overreach.
+- CI/CD pipeline leakage or unreviewed build scripts.
+- Unsigned/unprovenanced artifacts, missing SBOM.
+- Treat AI-generated code as untrusted until validated.
+- **Guardrail check:** Are there rules for dependency pinning, SBOM generation, artifact signing?
+
+---
+
+## Phase 3 — Guardrail Enforcement (Secure by Code)
+
+After completing the PWNISMS analysis and before writing code:
+
+1. **Review the exact shortlisted guardrails** produced by `{{GUARDRAILS_SELECTION_SKILL_DIR}}/SKILL.md`.
+2. **Classify applicability** — For each shortlisted guardrail, determine if it applies to the current task.
+3. **Apply during code generation:**
+   - `must` rules → mandatory implementation requirements. Every applicable `must` guardrail must be satisfied.
+   - `must_not` rules → hard prohibitions. Code must never violate an applicable `must_not` guardrail.
+4. **Flag conflicts** — If a guardrail conflicts with the user's explicit instruction, flag it and ask for confirmation.
+5. **Create new guardrails on the fly** — When PWNISMS analysis or code review reveals a recurring security pattern not captured by existing guardrails, create and apply it as a new guardrail (marked `source: "ide_generated"` in the VibeReview markdown). Include `title`, `rule_type` (must/must_not), `category`, `instruction`, and rationale in the notes.
+
+---
+
+## Phase 4 — Security-First Code Generation Rules
+
+When implementing code, enforce these baseline controls alongside project guardrails:
+
+1. Validate and constrain all untrusted input.
+2. Parameterize all queries and command-like invocations.
+3. Enforce least privilege for users, services, and workloads.
+4. Never hardcode secrets; use managed secret stores.
+5. Encrypt sensitive data in transit and at rest.
+6. Log security-relevant actions without leaking secrets/PII.
+7. Pin and verify dependencies and build artifacts.
+8. Return safe user errors; keep sensitive diagnostics internal.
+9. Add abuse protections (rate limits, lockouts, throttling) on exposed interfaces.
+
+---
+
+## Tailor for Architecture / Design Tasks
+
+When discussing designs before code exists:
+
+- Sketch a mental data flow: actors, data sent/received, storage, processing points.
+- Mark trust boundaries explicitly (client-backend, backend-DB, service-service, cloud-third party).
+- Identify where strong authentication/authorization is mandatory.
+- Identify where encryption in transit and at rest is mandatory.
+- Recommend concrete security patterns:
+  - Parameterized queries / ORM for DB access.
+  - Centralized authn/authz and role checks.
+  - Secrets manager / KMS for credentials and keys.
+  - mTLS or signed requests for service-to-service calls.
+- Review existing guardrails for design-level constraints.
+
+---
+
+## Phase 5 — VibeReview Sync (Post Threat Modelling)
+
+**MANDATORY:** After every threat modeling step that produces or modifies threat content, the main agent must update the `.vibreview/scans/*.md` artifact and call `sync_ai_ide_markdown` directly with raw markdown content.
+
+### What triggers the VibeReview sync
+
+- New threat model generated (any form: scenarios, data flows, attack trees, PWNISMS analysis)
+- Existing threat model updated or extended (new threats, refined mitigations, additional components)
+- Guardrails applied during a code-generation task (existing or IDE-generated)
+
+Do not call sync before implementation is complete unless the user explicitly asked only for threat modelling/design output. For coding tasks, the order is guardrail selection, PWNISMS, implementation, markdown sync.
+
+### What the VibeReview markdown must contain
+
+The main agent writes a structured `.md` artifact under `.vibreview/scans/` and uploads the raw markdown string through `sync_ai_ide_markdown`. That markdown should contain:
+
+- **Threat model findings**: threats mitigated, PWNISMS categories, severities, mitigations applied
+- **Best practices achieved**: structured practice entries with `practice_name`, `description`, and `category`
+- **Secure code snippets**: security-relevant code with explanations
+- **Guardrails applied**: all guardrails enforced during this session — both existing ones shortlisted earlier via `get_guardrails` (`source: "existing"`) and new ones the IDE agent created on the fly (`source: "ide_generated"`), each with satisfaction status
+- **Workflow metadata**: `chat_session_id`, `event_name` or `title`, required `summary`, and optional `workflow_name` / `workflow_description`
+
+### How to sync
+
+1. Read and follow `{{VIBEREVIEW_SYNC_SKILL_DIR}}/SKILL.md`.
+2. Write or update a file under `.vibreview/scans/`, ideally `.vibreview/scans/<chat_session_id>-<slugified-title-or-event-name>.md`.
+3. Put `chat_session_id`, `summary`, and either `title` or `event_name` in frontmatter.
+4. Include the required sections:
+   - `Best Practices Achieved`
+   - `Threats Mitigated`
+   - `Secure Code Snippets`
+   - `Guardrails Applied`
+   - `OWASP Top 10 2025 Mappings`
+5. Validate that:
+    - every threat entry includes `threat_name`, `pwnisms_category`, `severity`, and `mitigation_applied`
+   - every best-practice entry includes `practice_name`, `description`, and `category`
+   - every guardrail includes `title`, `rule_type`, `source`, and `satisfied`
+   - OWASP mappings use exact IDs and names
+   - snippets are grounded in actual code, not invented text
+   - no sibling `.md` files in `.vibreview/scans/` were read just to infer format or content
+6. Call `sync_ai_ide_markdown` directly with the finished raw markdown content. Do not pass JSON, extracted event objects, or summaries as the markdown.
+7. If sync fails, leave the artifact in `.vibreview/scans/` and report the failure clearly.
+
+---
+
+## Post-Generation Checklist
+
+Before finalizing output, confirm:
+
+- [ ] Scope, assumptions, and trust boundaries were explicit.
+- [ ] All 7 PWNISMS categories were checked (or marked N/A explicitly).
+- [ ] Top risks were prioritized by impact and likelihood.
+- [ ] Mitigations are concrete and actionable.
+- [ ] Residual risk and follow-up actions are stated.
+- [ ] Vibe guardrails were fetched and enforced (all applicable `must`/`must_not` rules satisfied).
+- [ ] Guardrail compliance summary is included in the response (existing + IDE-generated).
+- [ ] The VibeReview markdown was written under `.vibreview/scans/` and `sync_ai_ide_markdown` was called successfully with raw markdown content.
+
+If ANY box cannot be checked, you MUST flag the gap to the user with a specific remediation recommendation before finalizing the code.