@securityreviewai/securityreview-kit 0.1.47 → 0.1.49

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/dist/api.js +44 -0
  2. package/dist/commands/guardrails.js +13 -0
  3. package/dist/commands/init.js +88 -0
  4. package/dist/commands/profile.js +14 -0
  5. package/dist/commands/status.js +27 -0
  6. package/dist/commands/sync.js +6 -0
  7. package/dist/config.js +18 -0
  8. package/dist/fs.js +43 -0
  9. package/dist/index.js +44 -0
  10. package/dist/profile.js +113 -0
  11. package/dist/scaffold/claude-code.js +37 -0
  12. package/dist/scaffold/codex.js +35 -0
  13. package/dist/scaffold/cursor.js +39 -0
  14. package/dist/scaffold/gemini.js +10 -0
  15. package/dist/scaffold/index.js +22 -0
  16. package/dist/scaffold/mcp.js +15 -0
  17. package/dist/scaffold/rules.js +165 -0
  18. package/dist/scaffold/vibreview.js +24 -0
  19. package/dist/scaffold/vscode.js +22 -0
  20. package/dist/scaffold/windsurf.js +10 -0
  21. package/dist/sync/index.js +34 -0
  22. package/dist/sync/payload.js +23 -0
  23. package/dist/sync/state.js +12 -0
  24. package/dist/types.js +1 -0
  25. package/package.json +24 -30
  26. package/templates/claude/CLAUDE.md +13 -0
  27. package/templates/claude/agents/guardrail_profiler.md +12 -0
  28. package/templates/claude/agents/threat_modeler.md +5 -0
  29. package/templates/claude/skills/vibreview/SKILL.md +21 -0
  30. package/templates/claude/skills/vibreview/guardrail_patterns.md +12 -0
  31. package/templates/cursor/rules/vibreview-security.mdc +8 -0
  32. package/README.md +0 -105
  33. package/bin/securityreview-kit.js +0 -5
  34. package/src/cli.js +0 -109
  35. package/src/commands/init.js +0 -851
  36. package/src/commands/status.js +0 -99
  37. package/src/commands/switch-project.js +0 -207
  38. package/src/generators/mcp/claude.js +0 -85
  39. package/src/generators/mcp/claude.test.js +0 -64
  40. package/src/generators/mcp/codex.js +0 -70
  41. package/src/generators/mcp/codex.test.js +0 -43
  42. package/src/generators/mcp/cursor.js +0 -29
  43. package/src/generators/mcp/cursor.test.js +0 -50
  44. package/src/generators/mcp/gemini.js +0 -28
  45. package/src/generators/mcp/vscode.js +0 -48
  46. package/src/generators/mcp/vscode.test.js +0 -21
  47. package/src/generators/mcp/windsurf.js +0 -27
  48. package/src/generators/rules/antigravity.js +0 -22
  49. package/src/generators/rules/claude.js +0 -87
  50. package/src/generators/rules/claude.test.js +0 -60
  51. package/src/generators/rules/codex.js +0 -141
  52. package/src/generators/rules/codex.test.js +0 -59
  53. package/src/generators/rules/content.js +0 -110
  54. package/src/generators/rules/content.md +0 -57
  55. package/src/generators/rules/cursor.js +0 -128
  56. package/src/generators/rules/gemini.js +0 -13
  57. package/src/generators/rules/guardrails-init-profile.md +0 -56
  58. package/src/generators/rules/guardrails-profiler/SKILL.md +0 -130
  59. package/src/generators/rules/guardrails-profiler/references/signal-registry.json +0 -514
  60. package/src/generators/rules/guardrails-selection/SKILL.md +0 -187
  61. package/src/generators/rules/guardrails-selection/references/category-threat-map.md +0 -232
  62. package/src/generators/rules/guardrails_rule.md +0 -94
  63. package/src/generators/rules/hooks.json +0 -11
  64. package/src/generators/rules/skill.md +0 -256
  65. package/src/generators/rules/srai-profile.md +0 -32
  66. package/src/generators/rules/vibereview-sync/SKILL.md +0 -378
  67. package/src/generators/rules/vscode.js +0 -101
  68. package/src/generators/rules/vscode.test.js +0 -54
  69. package/src/generators/rules/windsurf.js +0 -13
  70. package/src/utils/constants.js +0 -95
  71. package/src/utils/cursor-agent-path.js +0 -67
  72. package/src/utils/cursor-cli-permissions.js +0 -28
  73. package/src/utils/detect.js +0 -27
  74. package/src/utils/fs-helpers.js +0 -82
  75. package/src/utils/guardrails-profiler-bundle.js +0 -84
  76. package/src/utils/ide-cli-install.js +0 -138
  77. package/src/utils/profiler-agent.js +0 -446
  78. package/src/utils/profiler-agent.test.js +0 -81
  79. package/src/utils/srai.js +0 -252
@@ -1,256 +0,0 @@
1
- ---
2
- name: PWNISMS Threat Modelling
3
- 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 before, during, and after implementation.
4
- ---
5
-
6
- # PWNISMS — Security-First Threat Modelling
7
-
8
- For EVERY security-relevant task (feature, bug fix, refactor, infra change, architecture design), run a threat model with PWNISMS.
9
-
10
- - Walk through all 7 categories explicitly.
11
- - If a category is not applicable, state it briefly and move on.
12
- - Anchor analysis to linked files, diffs, PRs, API specs, and diagrams whenever available.
13
- - Focus on realistic threats for the current context, not exhaustive attack catalogs.
14
-
15
- ---
16
-
17
- ## Phase 0 — Guardrail Context
18
-
19
- Before deep analysis, ensure the project-specific guardrail shortlist exists:
20
-
21
- 1. Use `{{GUARDRAILS_SELECTION_SKILL_DIR}}/SKILL.md`.
22
- 2. Resolve the project with `find_project_by_name` using `name="<SRAI_PROJECT_NAME>"`.
23
- 3. Call `get_guardrails`, shortlist intentionally for this task, then hydrate the exact shortlist with `get_guardrail_by_id`.
24
- 4. Keep the shortlisted existing guardrails in context for implementation and the final VibeReview markdown sync.
25
-
26
- 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.
27
-
28
- If SRAI is not available, proceed with the user-provided context and repository evidence, then clearly note that project guardrails could not be fetched.
29
-
30
- ---
31
-
32
- ## Phase 1 — Inputs to Gather
33
-
34
- Collect these quickly before deep analysis:
35
-
36
- - **Scope**: What is changing (feature, component, service, migration, PR)?
37
- - **Assets**: What must be protected (PII, credentials, tokens, configs, accounts, workflows)?
38
- - **Entry points**: How data enters/leaves (HTTP, queues, schedulers, CLI, webhooks, integrations)?
39
- - **Trust boundaries**: Where data crosses users/services/networks/privilege levels?
40
- - **Existing guardrails**: What shortlisted project-specific dos and don'ts apply (from Phase 0)?
41
-
42
- If the user provided specific code, diffs, or architecture artifacts, prioritize those as primary evidence.
43
-
44
- ---
45
-
46
- ## Phase 2 — Lightweight Workflow (PWNISMS)
47
-
48
- 1. **Clarify scope and assumptions**
49
- - Define the exact unit of analysis.
50
- - State assumptions explicitly (auth model, deployment boundary, tenant model, etc.).
51
-
52
- 2. **Map assets and flows**
53
- - List high-value assets and critical data paths.
54
- - List entry points and exits across trust boundaries.
55
- - Note which assets are covered by existing guardrails and which are not.
56
-
57
- 3. **Walk all 7 PWNISMS categories**
58
- - Identify plausible threats for each category.
59
- - Keep findings concrete and contextual.
60
- - For each threat, check if an existing guardrail already addresses it.
61
-
62
- 4. **Prioritize**
63
- - Select the top 3-7 risks by impact and likelihood.
64
- - Factor in existing mitigations from the codebase, user-provided context, and guardrails.
65
-
66
- 5. **Mitigate**
67
- - Propose concrete, implementable controls for each prioritized risk.
68
- - Map mitigations to specific guardrails where applicable.
69
- - If a mitigation represents a recurring pattern, propose it as a new guardrail candidate.
70
-
71
- 6. **Summarize residual risk**
72
- - Call out remaining risk, trade-offs, and follow-up actions.
73
- - Call out unknowns instead of silently guessing.
74
- - Note guardrail gaps — security patterns not yet captured by any guardrail.
75
-
76
- ---
77
-
78
- ## The 7 Categories (What to Check)
79
-
80
- ### P — Product
81
-
82
- Application and business-logic threats:
83
-
84
- - Input validation, injection, insecure deserialization.
85
- - Authorization gaps, privilege escalation, IDOR/BOLA.
86
- - Business logic abuse, replay/race conditions, unsafe redirects.
87
- - Error handling that leaks internals.
88
- - **Guardrail check:** Are there `must` / `must_not` rules for input validation, authorization patterns, error handling?
89
-
90
- ### W — Workload
91
-
92
- Compute and infrastructure threats:
93
-
94
- - Insecure container/runtime posture, over-privileged workload identity.
95
- - Weak host/orchestrator controls and segmentation.
96
- - Insecure data storage/backups and DB configuration.
97
- - Queue/broker abuse and poison-message handling gaps.
98
- - **Guardrail check:** Are there rules for container security, data-at-rest encryption, workload identity?
99
-
100
- ### N — Network
101
-
102
- Network and transport threats:
103
-
104
- - Missing/weak TLS, insecure service-to-service communication.
105
- - Exposed ports/endpoints and permissive ingress/egress.
106
- - Weak segmentation or lateral movement paths.
107
- - API-layer abuse controls missing (rate limits, request limits, CORS hardening).
108
- - **Guardrail check:** Are there rules for TLS enforcement, CORS policy, rate limiting?
109
-
110
- ### I — IAM (Identity & Access Management)
111
-
112
- Identity and authorization threats:
113
-
114
- - Broken authentication controls and token validation.
115
- - Missing least-privilege RBAC/ABAC.
116
- - Service-to-service auth gaps.
117
- - Escalation paths across users, roles, or services.
118
- - **Guardrail check:** Are there rules for auth mechanisms, session management, privilege boundaries?
119
-
120
- ### S — Secrets
121
-
122
- Credential and key management threats:
123
-
124
- - Secrets in code, images, logs, CI output, or defaults.
125
- - Weak rotation, revocation, or token lifetime policies.
126
- - Over-shared secrets across components.
127
- - Missing secret manager/KMS controls.
128
- - **Guardrail check:** Are there `must_not` rules against hardcoded secrets, `must` rules for secret manager usage?
129
-
130
- ### M — Monitoring (Logging & Observability)
131
-
132
- Detection and auditability threats:
133
-
134
- - Missing logs for auth, authorization, admin/data access events.
135
- - Sensitive data leakage in logs.
136
- - Missing alerts for abuse indicators.
137
- - Incomplete audit trails or weak log integrity.
138
- - **Guardrail check:** Are there rules for what must be logged and what must not appear in logs?
139
-
140
- ### S — Supply Chain
141
-
142
- Dependency and delivery threats:
143
-
144
- - Unpinned/unverified dependencies and vulnerable packages.
145
- - Third-party integration trust and scope overreach.
146
- - CI/CD pipeline leakage or unreviewed build scripts.
147
- - Unsigned/unprovenanced artifacts, missing SBOM.
148
- - Treat AI-generated code as untrusted until validated.
149
- - **Guardrail check:** Are there rules for dependency pinning, SBOM generation, artifact signing?
150
-
151
- ---
152
-
153
- ## Phase 3 — Guardrail Enforcement (Secure by Code)
154
-
155
- After completing the PWNISMS analysis and before writing code:
156
-
157
- 1. **Review the shortlisted hydrated guardrails** produced by `{{GUARDRAILS_SELECTION_SKILL_DIR}}/SKILL.md`.
158
- 2. **Classify applicability** — For each shortlisted guardrail, determine if it applies to the current task.
159
- 3. **Apply during code generation:**
160
- - `must` rules → mandatory implementation requirements. Every applicable `must` guardrail must be satisfied.
161
- - `must_not` rules → hard prohibitions. Code must never violate an applicable `must_not` guardrail.
162
- 4. **Flag conflicts** — If a guardrail conflicts with the user's explicit instruction, flag it and ask for confirmation.
163
- 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.
164
-
165
- ---
166
-
167
- ## Phase 4 — Security-First Code Generation Rules
168
-
169
- When implementing code, enforce these baseline controls alongside project guardrails:
170
-
171
- 1. Validate and constrain all untrusted input.
172
- 2. Parameterize all queries and command-like invocations.
173
- 3. Enforce least privilege for users, services, and workloads.
174
- 4. Never hardcode secrets; use managed secret stores.
175
- 5. Encrypt sensitive data in transit and at rest.
176
- 6. Log security-relevant actions without leaking secrets/PII.
177
- 7. Pin and verify dependencies and build artifacts.
178
- 8. Return safe user errors; keep sensitive diagnostics internal.
179
- 9. Add abuse protections (rate limits, lockouts, throttling) on exposed interfaces.
180
-
181
- ---
182
-
183
- ## Tailor for Architecture / Design Tasks
184
-
185
- When discussing designs before code exists:
186
-
187
- - Sketch a mental data flow: actors, data sent/received, storage, processing points.
188
- - Mark trust boundaries explicitly (client-backend, backend-DB, service-service, cloud-third party).
189
- - Identify where strong authentication/authorization is mandatory.
190
- - Identify where encryption in transit and at rest is mandatory.
191
- - Recommend concrete security patterns:
192
- - Parameterized queries / ORM for DB access.
193
- - Centralized authn/authz and role checks.
194
- - Secrets manager / KMS for credentials and keys.
195
- - mTLS or signed requests for service-to-service calls.
196
- - Review existing guardrails for design-level constraints.
197
-
198
- ---
199
-
200
- ## Phase 5 — VibeReview Sync (Post Threat Modelling)
201
-
202
- **MANDATORY:** After every threat modeling step that produces or modifies threat content, the main agent must update the `vibereview/*.md` artifact and call `sync_ai_ide_markdown` directly.
203
-
204
- ### What triggers the VibeReview sync
205
-
206
- - New threat model generated (any form: scenarios, data flows, attack trees, PWNISMS analysis)
207
- - Existing threat model updated or extended (new threats, refined mitigations, additional components)
208
- - Guardrails applied during a code-generation task (existing or IDE-generated)
209
-
210
- ### What the VibeReview markdown must contain
211
-
212
- The main agent writes a structured `.md` artifact under `vibereview/` and uploads it through `sync_ai_ide_markdown`. That markdown should contain:
213
-
214
- - **Threat model findings**: threats mitigated, PWNISMS categories, severities, mitigations applied
215
- - **Best practices achieved**: structured practice entries with `practice_name`, `description`, and `category`
216
- - **Secure code snippets**: security-relevant code with explanations
217
- - **Guardrails applied**: all guardrails enforced during this session — both existing ones shortlisted earlier via `get_guardrails` + `get_guardrail_by_id` (`source: "existing"`) and new ones the IDE agent created on the fly (`source: "ide_generated"`), each with satisfaction status
218
- - **Workflow metadata**: `chat_session_id`, `event_name` or `title`, required `summary`, and optional `workflow_name` / `workflow_description`
219
-
220
- ### How to sync
221
-
222
- 1. Read and follow `{{VIBEREVIEW_SYNC_SKILL_DIR}}/SKILL.md`.
223
- 2. Write or update a file under `vibereview/`, ideally `vibereview/<chat_session_id>-<slugified-title-or-event-name>.md`.
224
- 3. Put `chat_session_id`, `summary`, and either `title` or `event_name` in frontmatter.
225
- 4. Include the required sections:
226
- - `Best Practices Achieved`
227
- - `Threats Mitigated`
228
- - `Secure Code Snippets`
229
- - `Guardrails Applied`
230
- - `OWASP Top 10 2025 Mappings`
231
- 5. Validate that:
232
- - every threat entry includes `threat_name`, `pwnisms_category`, `severity`, and `mitigation_applied`
233
- - every best-practice entry includes `practice_name`, `description`, and `category`
234
- - every guardrail includes `title`, `rule_type`, `source`, and `satisfied`
235
- - OWASP mappings use exact IDs and names
236
- - snippets are grounded in actual code, not invented text
237
- - no sibling `.md` files in `vibereview/` were read just to infer format or content
238
- 6. Call `sync_ai_ide_markdown` directly with the finished markdown artifact.
239
- 7. If sync fails, leave the artifact in `vibereview/` and report the failure clearly.
240
-
241
- ---
242
-
243
- ## Post-Generation Checklist
244
-
245
- Before finalizing output, confirm:
246
-
247
- - [ ] Scope, assumptions, and trust boundaries were explicit.
248
- - [ ] All 7 PWNISMS categories were checked (or marked N/A explicitly).
249
- - [ ] Top risks were prioritized by impact and likelihood.
250
- - [ ] Mitigations are concrete and actionable.
251
- - [ ] Residual risk and follow-up actions are stated.
252
- - [ ] Vibe guardrails were fetched and enforced (all applicable `must`/`must_not` rules satisfied).
253
- - [ ] Guardrail compliance summary is included in the response (existing + IDE-generated).
254
- - [ ] The VibeReview markdown was written under `vibereview/` and `sync_ai_ide_markdown` was called successfully.
255
-
256
- If ANY box cannot be checked, you MUST flag the gap to the user with a specific remediation recommendation before finalizing the code.
@@ -1,32 +0,0 @@
1
- ---
2
- name: srai-profile
3
- description: Create and upload a SecurityReviewAI code profile using security-review-mcp
4
- ---
5
-
6
- # SRAI Profile Uploader
7
-
8
- Create a code profile from the current request and upload it to SRAI using `security-review-mcp`.
9
-
10
- Configured SRAI project name: `<SRAI_PROJECT_NAME>`
11
-
12
- ## Steps
13
-
14
- 1. Determine scope from the user prompt.
15
- - If the request is about a specific capability/module/endpoint, produce a **Feature Code Profile**.
16
- - If the request is broad, exploratory, or architecture-level, produce a **Codebase Code Profile**.
17
- 2. Build detailed profile content before any upload call.
18
- - Include purpose, boundaries, entry points, sensitive data, trust boundaries, integrations, threats, controls, and open risks.
19
- 3. Resolve the SRAI project.
20
- - Use the configured project name by default; if it is missing or ambiguous, ask the user to confirm it.
21
- - Call `find_project_by_name` with `name="<SRAI_PROJECT_NAME>"`.
22
- - If missing, call `list_projects`; if still missing, call `create_project` with `name="<SRAI_PROJECT_NAME>"`.
23
- 4. Upload generated markdown content with tool 11: `upload_document`.
24
- - Use this for raw markdown/text generated in the chat.
25
- - Use a clear document name such as `feature-code-profile-<feature>.md` or `codebase-code-profile-<repo>.md`.
26
- 5. Upload files/diagrams with tool 10: `upload_document` when needed.
27
- - Provide base64 file content and file name.
28
- - Set `document_type` to `Component Diagram` for architecture diagrams.
29
- - Set `document_type` to `Uploaded Knowledgebase doc` for other document uploads.
30
- 6. Confirm the result.
31
- - Report project name, upload tool used, document name, and that processing is asynchronous.
32
- - If upload fails, return exact error details and next retry step.
@@ -1,378 +0,0 @@
1
- ---
2
- name: vibereview-sync
3
- 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.
4
- ---
5
-
6
- # VibeReview Markdown Sync
7
-
8
- Configured SRAI project name: `<SRAI_PROJECT_NAME>`
9
-
10
- Use this skill whenever threat modelling output exists or security guardrail compliance must be synchronized to SRAI.
11
-
12
- 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.
13
-
14
- ## Core Rules
15
-
16
- 1. Write the artifact under `vibereview/`.
17
- 2. Author the markdown from the current task context only.
18
- 3. Do not read other `.md` files in `vibereview/` to infer structure, copy content, or merge state.
19
- 4. If the current session file path is already known, update that one file directly.
20
- 5. If the current session file does not exist yet, create a new file using a stable name such as:
21
-
22
- ```text
23
- vibereview/<chat_session_id>-<slugified-title-or-event-name>.md
24
- ```
25
-
26
- 6. Validate the markdown before calling `sync_ai_ide_markdown`.
27
- 7. If sync fails, leave the file on disk and report the failure clearly.
28
-
29
- ## Why You Must Not Read Sibling Files
30
-
31
- 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.
32
-
33
- Treat each VibeReview artifact as self-contained. The current artifact must be fully authorable from:
34
-
35
- - the current user request
36
- - the current session context
37
- - the threat model produced in this task
38
- - the exact guardrail shortlist preserved in context
39
- - the real code snippets touched in this task
40
-
41
- ## Required Authoring Workflow
42
-
43
- ### Step 1: Collect the required inputs
44
-
45
- Before writing the markdown, confirm you have:
46
-
47
- - a stable `chat_session_id`
48
- - a concise `summary`
49
- - either `title` or `event_name`
50
- - the exact existing guardrails shortlisted earlier
51
- - any `ide_generated` guardrails created during this task
52
- - grounded threat entries
53
- - grounded code snippets from actual files
54
- - exact OWASP Top 10 2025 mappings when applicable
55
-
56
- If any required field is missing, resolve it from current context before writing. Do not invent data.
57
-
58
- ### Step 2: Write YAML frontmatter
59
-
60
- The frontmatter should use this shape:
61
-
62
- ```yaml
63
- ---
64
- chat_session_id: "cursor-chat-7f3b2f44-8c4d-4d4a-9f1e-2b6a4c91b201"
65
- workflow_name: "User Auth Hardening"
66
- workflow_description: "Security improvements for auth flow handling in the current IDE session"
67
- event_name: "Hardened AI IDE sync ingestion and workflow reuse"
68
- 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."
69
- external_id: "ai-ide-sync-2026-04-21-001"
70
- ---
71
- ```
72
-
73
- ### Frontmatter rules
74
-
75
- - `chat_session_id` is required.
76
- - `summary` is required.
77
- - At least one of `event_name` or `title` is required.
78
- - `workflow_name` is optional.
79
- - `workflow_description` is optional.
80
- - `external_id` is optional.
81
- - If `workflow_name` is omitted, the server may derive it from the title.
82
- - Do not rely on `developer_name` or `developer_email` in markdown. The server ignores them when authenticated API identity exists.
83
-
84
- ## Required Markdown Structure
85
-
86
- Use this top-level shape:
87
-
88
- ```md
89
- # AI IDE Sync Event
90
-
91
- ## Event Identity
92
- ...
93
-
94
- ## Summary
95
- ...
96
-
97
- # Threats Mitigated
98
- ...
99
-
100
- # Best Practices Achieved
101
- ...
102
-
103
- # Secure Code Snippets
104
- ...
105
-
106
- # Guardrails Applied
107
- ...
108
-
109
- # OWASP Top 10 2025 Mappings
110
- ...
111
- ```
112
-
113
- The exact heading levels may vary slightly, but the section names should stay stable and obvious.
114
-
115
- ## Event Identity Section
116
-
117
- Preferred structure:
118
-
119
- ```md
120
- ## Event Identity
121
-
122
- - chat_session_id: `cursor-chat-7f3b2f44-8c4d-4d4a-9f1e-2b6a4c91b201`
123
- - workflow_name: `User Auth Hardening`
124
- - event_name: `Hardened AI IDE sync ingestion and workflow reuse`
125
- - external_id: `ai-ide-sync-2026-04-21-001`
126
- ```
127
-
128
- ## Summary Section
129
-
130
- Repeat the summary in prose under `## Summary`.
131
-
132
- ## Threats Mitigated Section
133
-
134
- Each threat entry must include:
135
-
136
- - `threat_name`
137
- - `pwnisms_category`
138
- - `severity`
139
- - `mitigation_applied`
140
-
141
- When code exists, include a `### Code Snippet` subsection with:
142
-
143
- - `file_path`
144
- - `language`
145
- - `explanation`
146
- - a fenced code block containing real code
147
-
148
- Preferred example:
149
-
150
- ````md
151
- # Threats Mitigated
152
-
153
- ## Threat 1
154
-
155
- - threat_name: Missing session identity can attach events to the wrong workflow
156
- - pwnisms_category: IAM
157
- - severity: High
158
- - mitigation_applied: The server now requires a stable `chat_session_id` and uses it to resolve or create the workflow before persisting the event.
159
-
160
- ### Code Snippet
161
-
162
- - file_path: `app/api/external_ai_ide.py`
163
- - language: `python`
164
- - explanation: This prevents ambiguous workflow association and ensures repeated syncs from the same IDE chat session map to the same workflow.
165
-
166
- ```python
167
- chat_session_id = str(
168
- frontmatter.get("chat_session_id")
169
- or extracted.chat_session_id
170
- or ""
171
- ).strip()
172
-
173
- if not chat_session_id:
174
- raise ValueError("chat_session_id could not be resolved from markdown content")
175
- ```
176
- ````
177
-
178
- ### Threat authoring rules
179
-
180
- - Keep each threat clearly separated.
181
- - Do not collapse multiple threats into one malformed block.
182
- - Always close fenced code blocks.
183
- - Never let prose spill into the next threat entry.
184
- - PWNISMS categories must be one of:
185
- - `Product`
186
- - `Workload`
187
- - `Network`
188
- - `IAM`
189
- - `Secrets`
190
- - `Monitoring`
191
- - `Supply Chain`
192
- - Severity should be one of:
193
- - `Critical`
194
- - `High`
195
- - `Medium`
196
- - `Low`
197
-
198
- ## Best Practices Achieved Section
199
-
200
- Use structured practice entries, not plain bullet-only lists.
201
-
202
- ````md
203
- # Best Practices Achieved
204
-
205
- ## Practice 1
206
- - practice_name: Stable workflow correlation
207
- - description: Used a stable chat session identifier to ensure repeated syncs map to the same workflow.
208
- - category: identity
209
-
210
- ## Practice 2
211
- - practice_name: Server-side workflow orchestration
212
- - description: Kept workflow and event creation on the server instead of relying on IDE-side orchestration.
213
- - category: design
214
-
215
- ## Practice 3
216
- - practice_name: Required field validation
217
- - description: Validated required event identity fields before persisting security review data.
218
- - category: validation
219
- ````
220
-
221
- ### Best practice rules
222
-
223
- - Each entry should be introduced with a stable heading such as `## Practice 1`, `## Practice 2`, and so on.
224
- - Each entry must include:
225
- - `practice_name`
226
- - `description`
227
- - `category`
228
- - Keep the values concise and grounded in the actual work completed.
229
- - Do not turn this section into freeform paragraphs.
230
- - Do not reduce this section to plain bullet statements without field names.
231
-
232
- ## Secure Code Snippets Section
233
-
234
- Each snippet entry should include:
235
-
236
- - `file_path`
237
- - `language`
238
- - `explanation`
239
- - a fenced code block with real code
240
-
241
- Preferred example:
242
-
243
- ````md
244
- # Secure Code Snippets
245
-
246
- ## Snippet 1
247
-
248
- - file_path: `app/api/external_ai_ide.py`
249
- - language: `python`
250
- - explanation: This is security-relevant because it isolates background processing from the request lifecycle and ensures the authenticated developer identity is propagated server-side.
251
-
252
- ```python
253
- async def _process_ai_ide_markdown_ingestion(
254
- *,
255
- project_id: int,
256
- ingestion_id: str,
257
- filename: str,
258
- markdown_text: str,
259
- developer_name: str,
260
- developer_email: str,
261
- ) -> None:
262
- logger.info(
263
- "Starting AI IDE markdown ingestion %s for project %s",
264
- ingestion_id,
265
- project_id,
266
- )
267
- ```
268
- ````
269
-
270
- ### Secure snippet rules
271
-
272
- - Snippets must be real code, not invented examples.
273
- - Prefer snippets already cited in threat mitigations when they are strongly relevant.
274
- - Use fenced code blocks.
275
- - Keep snippets focused and bounded.
276
-
277
- ## Guardrails Applied Section
278
-
279
- Each guardrail entry must include:
280
-
281
- - `title`
282
- - `rule_type`
283
- - `category`
284
- - `instruction`
285
- - `source`
286
- - `satisfied`
287
- - `notes`
288
-
289
- Preferred example:
290
-
291
- ```md
292
- # Guardrails Applied
293
-
294
- ## Guardrail 1
295
-
296
- - title: Require stable AI IDE session identity
297
- - rule_type: must
298
- - category: Identity
299
- - instruction: Every AI IDE sync markdown must include a stable chat_session_id so workflow association is deterministic.
300
- - source: existing
301
- - satisfied: true
302
- - notes: Enforced during markdown ingestion before workflow lookup or workflow creation.
303
- ```
304
-
305
- ### Guardrail rules
306
-
307
- - `rule_type` must be `must` or `must_not`.
308
- - `source` must be `existing` or `ide_generated`.
309
- - `satisfied` must be `true` or `false`.
310
- - Do not drop shortlisted existing guardrails even when unsatisfied.
311
- - If a guardrail was not fully satisfied, keep it and explain why in `notes`.
312
-
313
- ## OWASP Top 10 2025 Mappings Section
314
-
315
- Use exact IDs and names. Preferred structures:
316
-
317
- ```md
318
- # OWASP Top 10 2025 Mappings
319
-
320
- - A07: Authentication Failures
321
- - A06: Insecure Design
322
- - A10: Mishandling of Exceptional Conditions
323
- ```
324
-
325
- or
326
-
327
- ```md
328
- # OWASP Top 10 2025 Mappings
329
-
330
- - category_id: A07
331
- category_name: Authentication Failures
332
- - category_id: A06
333
- category_name: Insecure Design
334
- ```
335
-
336
- Allowed values:
337
-
338
- - `A01` Broken Access Control
339
- - `A02` Security Misconfiguration
340
- - `A03` Software Supply Chain Failures
341
- - `A04` Cryptographic Failures
342
- - `A05` Injection
343
- - `A06` Insecure Design
344
- - `A07` Authentication Failures
345
- - `A08` Software or Data Integrity Failures
346
- - `A09` Security Logging and Alerting Failures
347
- - `A10` Mishandling of Exceptional Conditions
348
-
349
- ## Validation Checklist Before Sync
350
-
351
- Before calling `sync_ai_ide_markdown`, verify all of the following:
352
-
353
- - The file is under `vibereview/`.
354
- - You did not read sibling markdown files in `vibereview/`.
355
- - `chat_session_id` exists in frontmatter.
356
- - `summary` exists in frontmatter.
357
- - `event_name` or `title` exists in frontmatter.
358
- - The `Event Identity` section exists.
359
- - The `Summary` section exists.
360
- - The `Threats Mitigated` section exists.
361
- - The `Best Practices Achieved` section exists.
362
- - The `Secure Code Snippets` section exists.
363
- - The `Guardrails Applied` section exists.
364
- - The `OWASP Top 10 2025 Mappings` section exists.
365
- - Every threat entry is structurally complete.
366
- - Every code fence is closed.
367
- - Every snippet is grounded in real code.
368
- - Every guardrail entry is structurally complete.
369
- - OWASP IDs and names are exact.
370
-
371
- ## Final Step
372
-
373
- After validation:
374
-
375
- 1. Save the markdown artifact under `vibereview/`.
376
- 2. Call `sync_ai_ide_markdown` directly with that file's contents or path, depending on the tool interface exposed by the host.
377
- 3. If sync succeeds, report success briefly.
378
- 4. If sync fails, report failure clearly and leave the markdown artifact intact for retry.