@securityreviewai/securityreview-kit 0.1.49 → 0.1.50

package/templates/shared/vibereview-sync/SKILL.md

@@ -0,0 +1,378 @@
+---
+name: vibereview-sync
+description: Write and synchronize a structured VibeReview markdown artifact under vibereview/ for the current security-relevant session. Use after threat modelling or guardrail-enforced implementation.
+---
+
+# VibeReview Markdown Sync
+
+Configured SRAI project name: `<SRAI_PROJECT_NAME>`
+
+Use this skill whenever threat modelling output exists or security guardrail compliance must be synchronized to SRAI.
+
+This skill exists to make the markdown deterministic, grounded, and parseable without depending on a separate subagent. The same agent that performed the work should author the markdown and call `sync_ai_ide_markdown` directly.
+
+## Core Rules
+
+1. Write the artifact under `vibereview/`.
+2. Author the markdown from the current task context only.
+3. Do not read other `.md` files in `vibereview/` to infer structure, copy content, or merge state.
+4. If the current session file path is already known, update that one file directly.
+5. If the current session file does not exist yet, create a new file using a stable name such as:
+
+```text
+vibereview/<chat_session_id>-<slugified-title-or-event-name>.md
+```
+
+6. Validate the markdown before calling `sync_ai_ide_markdown`.
+7. If sync fails, leave the file on disk and report the failure clearly.
+
+## Why You Must Not Read Sibling Files
+
+Other markdown files in `vibereview/` may belong to different sessions, different workflows, or partially complete work. Reading them introduces drift and causes downstream extraction failures.
+
+Treat each VibeReview artifact as self-contained. The current artifact must be fully authorable from:
+
+- the current user request
+- the current session context
+- the threat model produced in this task
+- the exact guardrail shortlist preserved in context
+- the real code snippets touched in this task
+
+## Required Authoring Workflow
+
+### Step 1: Collect the required inputs
+
+Before writing the markdown, confirm you have:
+
+- a stable `chat_session_id`
+- a concise `summary`
+- either `title` or `event_name`
+- the exact existing guardrails shortlisted earlier
+- any `ide_generated` guardrails created during this task
+- grounded threat entries
+- grounded code snippets from actual files
+- exact OWASP Top 10 2025 mappings when applicable
+
+If any required field is missing, resolve it from current context before writing. Do not invent data.
+
+### Step 2: Write YAML frontmatter
+
+The frontmatter should use this shape:
+
+```yaml
+---
+chat_session_id: "cursor-chat-7f3b2f44-8c4d-4d4a-9f1e-2b6a4c91b201"
+workflow_name: "User Auth Hardening"
+workflow_description: "Security improvements for auth flow handling in the current IDE session"
+event_name: "Hardened AI IDE sync ingestion and workflow reuse"
+summary: "This change moved AI IDE sync handling to the server so workflow resolution and event creation happen deterministically after markdown upload. We enforced stable session identity, validated required event fields, and added structured extraction for threats, guardrails, secure code snippets, and OWASP mappings. The endpoint now accepts markdown, returns immediately, and continues processing in the background."
+external_id: "ai-ide-sync-2026-04-21-001"
+---
+```
+
+### Frontmatter rules
+
+- `chat_session_id` is required.
+- `summary` is required.
+- At least one of `event_name` or `title` is required.
+- `workflow_name` is optional.
+- `workflow_description` is optional.
+- `external_id` is optional.
+- If `workflow_name` is omitted, the server may derive it from the title.
+- Do not rely on `developer_name` or `developer_email` in markdown. The server ignores them when authenticated API identity exists.
+
+## Required Markdown Structure
+
+Use this top-level shape:
+
+```md
+# AI IDE Sync Event
+
+## Event Identity
+...
+
+## Summary
+...
+
+# Threats Mitigated
+...
+
+# Best Practices Achieved
+...
+
+# Secure Code Snippets
+...
+
+# Guardrails Applied
+...
+
+# OWASP Top 10 2025 Mappings
+...
+```
+
+The exact heading levels may vary slightly, but the section names should stay stable and obvious.
+
+## Event Identity Section
+
+Preferred structure:
+
+```md
+## Event Identity
+
+- chat_session_id: `cursor-chat-7f3b2f44-8c4d-4d4a-9f1e-2b6a4c91b201`
+- workflow_name: `User Auth Hardening`
+- event_name: `Hardened AI IDE sync ingestion and workflow reuse`
+- external_id: `ai-ide-sync-2026-04-21-001`
+```
+
+## Summary Section
+
+Repeat the summary in prose under `## Summary`.
+
+## Threats Mitigated Section
+
+Each threat entry must include:
+
+- `threat_name`
+- `pwnisms_category`
+- `severity`
+- `mitigation_applied`
+
+When code exists, include a `### Code Snippet` subsection with:
+
+- `file_path`
+- `language`
+- `explanation`
+- a fenced code block containing real code
+
+Preferred example:
+
+````md
+# Threats Mitigated
+
+## Threat 1
+
+- threat_name: Missing session identity can attach events to the wrong workflow
+- pwnisms_category: IAM
+- severity: High
+- mitigation_applied: The server now requires a stable `chat_session_id` and uses it to resolve or create the workflow before persisting the event.
+
+### Code Snippet
+
+- file_path: `app/api/external_ai_ide.py`
+- language: `python`
+- explanation: This prevents ambiguous workflow association and ensures repeated syncs from the same IDE chat session map to the same workflow.
+
+```python
+chat_session_id = str(
+    frontmatter.get("chat_session_id")
+    or extracted.chat_session_id
+    or ""
+).strip()
+
+if not chat_session_id:
+    raise ValueError("chat_session_id could not be resolved from markdown content")
+```
+````
+
+### Threat authoring rules
+
+- Keep each threat clearly separated.
+- Do not collapse multiple threats into one malformed block.
+- Always close fenced code blocks.
+- Never let prose spill into the next threat entry.
+- PWNISMS categories must be one of:
+  - `Product`
+  - `Workload`
+  - `Network`
+  - `IAM`
+  - `Secrets`
+  - `Monitoring`
+  - `Supply Chain`
+- Severity should be one of:
+  - `Critical`
+  - `High`
+  - `Medium`
+  - `Low`
+
+## Best Practices Achieved Section
+
+Use structured practice entries, not plain bullet-only lists.
+
+````md
+# Best Practices Achieved
+
+## Practice 1
+- practice_name: Stable workflow correlation
+- description: Used a stable chat session identifier to ensure repeated syncs map to the same workflow.
+- category: identity
+
+## Practice 2
+- practice_name: Server-side workflow orchestration
+- description: Kept workflow and event creation on the server instead of relying on IDE-side orchestration.
+- category: design
+
+## Practice 3
+- practice_name: Required field validation
+- description: Validated required event identity fields before persisting security review data.
+- category: validation
+````
+
+### Best practice rules
+
+- Each entry should be introduced with a stable heading such as `## Practice 1`, `## Practice 2`, and so on.
+- Each entry must include:
+  - `practice_name`
+  - `description`
+  - `category`
+- Keep the values concise and grounded in the actual work completed.
+- Do not turn this section into freeform paragraphs.
+- Do not reduce this section to plain bullet statements without field names.
+
+## Secure Code Snippets Section
+
+Each snippet entry should include:
+
+- `file_path`
+- `language`
+- `explanation`
+- a fenced code block with real code
+
+Preferred example:
+
+````md
+# Secure Code Snippets
+
+## Snippet 1
+
+- file_path: `app/api/external_ai_ide.py`
+- language: `python`
+- explanation: This is security-relevant because it isolates background processing from the request lifecycle and ensures the authenticated developer identity is propagated server-side.
+
+```python
+async def _process_ai_ide_markdown_ingestion(
+    *,
+    project_id: int,
+    ingestion_id: str,
+    filename: str,
+    markdown_text: str,
+    developer_name: str,
+    developer_email: str,
+) -> None:
+    logger.info(
+        "Starting AI IDE markdown ingestion %s for project %s",
+        ingestion_id,
+        project_id,
+    )
+```
+````
+
+### Secure snippet rules
+
+- Snippets must be real code, not invented examples.
+- Prefer snippets already cited in threat mitigations when they are strongly relevant.
+- Use fenced code blocks.
+- Keep snippets focused and bounded.
+
+## Guardrails Applied Section
+
+Each guardrail entry must include:
+
+- `title`
+- `rule_type`
+- `category`
+- `instruction`
+- `source`
+- `satisfied`
+- `notes`
+
+Preferred example:
+
+```md
+# Guardrails Applied
+
+## Guardrail 1
+
+- title: Require stable AI IDE session identity
+- rule_type: must
+- category: Identity
+- instruction: Every AI IDE sync markdown must include a stable chat_session_id so workflow association is deterministic.
+- source: existing
+- satisfied: true
+- notes: Enforced during markdown ingestion before workflow lookup or workflow creation.
+```
+
+### Guardrail rules
+
+- `rule_type` must be `must` or `must_not`.
+- `source` must be `existing` or `ide_generated`.
+- `satisfied` must be `true` or `false`.
+- Do not drop shortlisted existing guardrails even when unsatisfied.
+- If a guardrail was not fully satisfied, keep it and explain why in `notes`.
+
+## OWASP Top 10 2025 Mappings Section
+
+Use exact IDs and names. Preferred structures:
+
+```md
+# OWASP Top 10 2025 Mappings
+
+- A07: Authentication Failures
+- A06: Insecure Design
+- A10: Mishandling of Exceptional Conditions
+```
+
+or
+
+```md
+# OWASP Top 10 2025 Mappings
+
+- category_id: A07
+  category_name: Authentication Failures
+- category_id: A06
+  category_name: Insecure Design
+```
+
+Allowed values:
+
+- `A01` Broken Access Control
+- `A02` Security Misconfiguration
+- `A03` Software Supply Chain Failures
+- `A04` Cryptographic Failures
+- `A05` Injection
+- `A06` Insecure Design
+- `A07` Authentication Failures
+- `A08` Software or Data Integrity Failures
+- `A09` Security Logging and Alerting Failures
+- `A10` Mishandling of Exceptional Conditions
+
+## Validation Checklist Before Sync
+
+Before calling `sync_ai_ide_markdown`, verify all of the following:
+
+- The file is under `vibereview/`.
+- You did not read sibling markdown files in `vibereview/`.
+- `chat_session_id` exists in frontmatter.
+- `summary` exists in frontmatter.
+- `event_name` or `title` exists in frontmatter.
+- The `Event Identity` section exists.
+- The `Summary` section exists.
+- The `Threats Mitigated` section exists.
+- The `Best Practices Achieved` section exists.
+- The `Secure Code Snippets` section exists.
+- The `Guardrails Applied` section exists.
+- The `OWASP Top 10 2025 Mappings` section exists.
+- Every threat entry is structurally complete.
+- Every code fence is closed.
+- Every snippet is grounded in real code.
+- Every guardrail entry is structurally complete.
+- OWASP IDs and names are exact.
+
+## Final Step
+
+After validation:
+
+1. Save the markdown artifact under `vibereview/`.
+2. Call `sync_ai_ide_markdown` directly with that file's contents or path, depending on the tool interface exposed by the host.
+3. If sync succeeds, report success briefly.
+4. If sync fails, report failure clearly and leave the markdown artifact intact for retry.