@securityreviewai/securityreview-kit 0.1.48 → 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.
- package/dist/api.js +44 -0
- package/dist/commands/guardrails.js +13 -0
- package/dist/commands/init.js +88 -0
- package/dist/commands/profile.js +14 -0
- package/dist/commands/status.js +27 -0
- package/dist/commands/sync.js +6 -0
- package/dist/config.js +18 -0
- package/dist/fs.js +43 -0
- package/dist/index.js +44 -0
- package/dist/profile.js +113 -0
- package/dist/scaffold/claude-code.js +37 -0
- package/dist/scaffold/codex.js +35 -0
- package/dist/scaffold/cursor.js +39 -0
- package/dist/scaffold/gemini.js +10 -0
- package/dist/scaffold/index.js +22 -0
- package/dist/scaffold/mcp.js +15 -0
- package/dist/scaffold/rules.js +165 -0
- package/dist/scaffold/vibreview.js +24 -0
- package/dist/scaffold/vscode.js +22 -0
- package/dist/scaffold/windsurf.js +10 -0
- package/dist/sync/index.js +34 -0
- package/dist/sync/payload.js +23 -0
- package/dist/sync/state.js +12 -0
- package/dist/types.js +1 -0
- package/package.json +24 -30
- package/templates/claude/CLAUDE.md +13 -0
- package/templates/claude/agents/guardrail_profiler.md +12 -0
- package/templates/claude/agents/threat_modeler.md +5 -0
- package/templates/claude/skills/vibreview/SKILL.md +21 -0
- package/templates/claude/skills/vibreview/guardrail_patterns.md +12 -0
- package/templates/cursor/rules/vibreview-security.mdc +8 -0
- package/README.md +0 -105
- package/bin/securityreview-kit.js +0 -5
- package/src/cli.js +0 -109
- package/src/commands/init.js +0 -851
- package/src/commands/status.js +0 -99
- package/src/commands/switch-project.js +0 -207
- package/src/generators/mcp/claude.js +0 -85
- package/src/generators/mcp/claude.test.js +0 -64
- package/src/generators/mcp/codex.js +0 -70
- package/src/generators/mcp/codex.test.js +0 -43
- package/src/generators/mcp/cursor.js +0 -29
- package/src/generators/mcp/cursor.test.js +0 -50
- package/src/generators/mcp/gemini.js +0 -28
- package/src/generators/mcp/vscode.js +0 -29
- package/src/generators/mcp/windsurf.js +0 -27
- package/src/generators/rules/antigravity.js +0 -22
- package/src/generators/rules/claude.js +0 -87
- package/src/generators/rules/claude.test.js +0 -60
- package/src/generators/rules/codex.js +0 -141
- package/src/generators/rules/codex.test.js +0 -59
- package/src/generators/rules/content.js +0 -110
- package/src/generators/rules/content.md +0 -57
- package/src/generators/rules/cursor.js +0 -128
- package/src/generators/rules/gemini.js +0 -13
- package/src/generators/rules/guardrails-init-profile.md +0 -56
- package/src/generators/rules/guardrails-profiler/SKILL.md +0 -130
- package/src/generators/rules/guardrails-profiler/references/signal-registry.json +0 -514
- package/src/generators/rules/guardrails-selection/SKILL.md +0 -187
- package/src/generators/rules/guardrails-selection/references/category-threat-map.md +0 -232
- package/src/generators/rules/guardrails_rule.md +0 -94
- package/src/generators/rules/hooks.json +0 -11
- package/src/generators/rules/skill.md +0 -256
- package/src/generators/rules/srai-profile.md +0 -32
- package/src/generators/rules/vibereview-sync/SKILL.md +0 -378
- package/src/generators/rules/vscode.js +0 -101
- package/src/generators/rules/vscode.test.js +0 -54
- package/src/generators/rules/windsurf.js +0 -13
- package/src/utils/constants.js +0 -95
- package/src/utils/cursor-agent-path.js +0 -67
- package/src/utils/cursor-cli-permissions.js +0 -28
- package/src/utils/detect.js +0 -27
- package/src/utils/fs-helpers.js +0 -82
- package/src/utils/guardrails-profiler-bundle.js +0 -84
- package/src/utils/ide-cli-install.js +0 -138
- package/src/utils/profiler-agent.js +0 -446
- package/src/utils/profiler-agent.test.js +0 -81
- 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.
|