agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

package/content/plugins/reviews/skills/agileflow-pr-reviewer/references/security-patterns.md

@@ -0,0 +1,328 @@
+# Security Patterns Reference
+
+**Load this when:** reviewing code with security implications — auth changes, user input handling, database queries, file operations, cryptography, or external integrations.
+
+---
+
+## OWASP Top 10 (2021) — Review Checklist
+
+### A01: Broken Access Control
+
+The #1 most common vulnerability. Users can access resources or perform actions they shouldn't.
+
+**Patterns to look for:**
+
+```js
+// BAD — IDOR: user can access any account by changing the ID
+app.get("/api/orders/:orderId", async (req, res) => {
+  const order = await Order.findById(req.params.orderId);
+  res.json(order); // No check that order belongs to req.user!
+});
+
+// GOOD — ownership check before returning data
+app.get("/api/orders/:orderId", requireAuth, async (req, res) => {
+  const order = await Order.findById(req.params.orderId);
+  if (!order || order.userId !== req.user.id) {
+    return res.status(404).json({ error: "Not found" });
+  }
+  res.json(order);
+});
+```
+
+**What to check:**
+
+- Every endpoint that returns or modifies user data checks ownership
+- Admin endpoints have role-based access checks
+- Resource IDs are not predictable/guessable (UUIDs, not auto-increment)
+- Access checks are server-side, not just UI-hidden
+
+---
+
+### A02: Cryptographic Failures
+
+Sensitive data exposed due to weak encryption, missing encryption, or improper key management.
+
+**Patterns to look for:**
+
+```python
+# BAD — MD5 for password hashing (trivially crackable)
+import hashlib
+password_hash = hashlib.md5(password.encode()).hexdigest()
+
+# GOOD — bcrypt with appropriate cost factor
+import bcrypt
+password_hash = bcrypt.hashpw(password.encode(), bcrypt.gensalt(rounds=12))
+
+# BAD — SHA256 without salt (rainbow table vulnerable)
+password_hash = hashlib.sha256(password.encode()).hexdigest()
+```
+
+```js
+// BAD — token generated with Math.random() (predictable)
+const token = Math.random().toString(36).slice(2);
+
+// GOOD — cryptographically secure token
+const token = crypto.randomBytes(32).toString("hex");
+```
+
+**What to check:**
+
+- Passwords use bcrypt, argon2, or scrypt (never MD5, SHA1, SHA256 alone)
+- Session tokens use `crypto.randomBytes` or equivalent
+- Sensitive data (PII, payment info) encrypted at rest in database
+- TLS enforced — no HTTP fallback for sensitive operations
+- API keys / secrets not hardcoded in source code (use env vars)
+- JWT `alg: none` not accepted
+
+---
+
+### A03: Injection
+
+User input flows into interpreters (SQL, shell, HTML, LDAP) without sanitisation.
+
+**SQL Injection:**
+
+```js
+// BAD — raw string interpolation
+const user = await db.query(`SELECT * FROM users WHERE email = '${email}'`);
+// Payload: ' OR '1'='1 — dumps all users
+
+// GOOD — parameterised query
+const user = await db.query("SELECT * FROM users WHERE email = $1", [email]);
+```
+
+```python
+# BAD
+cursor.execute(f"SELECT * FROM users WHERE email = '{email}'")
+
+# GOOD
+cursor.execute("SELECT * FROM users WHERE email = %s", (email,))
+```
+
+**Command Injection:**
+
+```js
+// BAD — user input in shell command
+const { execSync } = require("child_process");
+execSync(`convert ${req.body.filename} output.jpg`);
+// Payload: "file.jpg && rm -rf /"
+
+// GOOD — use a library instead of shell, or validate input strictly
+const sharp = require("sharp");
+await sharp(sanitisedFilePath).toFile("output.jpg");
+```
+
+**Path Traversal:**
+
+```js
+// BAD — allows ../../../etc/passwd
+const filePath = path.join("/uploads", req.params.filename);
+
+// GOOD — resolve and check it stays inside the intended directory
+const filePath = path.resolve("/uploads", req.params.filename);
+if (!filePath.startsWith(path.resolve("/uploads"))) {
+  return res.status(400).json({ error: "Invalid path" });
+}
+```
+
+---
+
+### A04: Insecure Design
+
+Architectural flaws in security model. These can't be fixed by patching code — they require design changes.
+
+**Red flags to raise:**
+
+- Passwords or tokens sent as URL query parameters (appear in server logs)
+- Email-based "magic link" login with no expiry
+- Password reset that reveals whether an email is registered (email enumeration)
+- Rate limiting absent on authentication endpoints (brute-force vulnerable)
+- File uploads with no type validation or virus scanning
+
+---
+
+### A05: Security Misconfiguration
+
+**Patterns to check:**
+
+- `DEBUG=true` or equivalent in production code
+- Error responses include stack traces or internal paths
+- Default credentials in database or admin panel setup
+- CORS configured as `Access-Control-Allow-Origin: *` on authenticated endpoints
+- HTTP security headers missing (CSP, X-Frame-Options, X-Content-Type-Options)
+- Directory listing enabled on static file server
+
+---
+
+### A06: Vulnerable and Outdated Components
+
+Not a code review finding, but flag if you see:
+
+- `require('crypto-js')` for password hashing (use Node's built-in `crypto` or `bcrypt`)
+- Old `jsonwebtoken` patterns without algorithm validation
+- Direct eval of JSON from external sources
+- Known-vulnerable package versions (check with `npm audit` / `pip-audit`)
+
+---
+
+### A07: Identification and Authentication Failures
+
+```js
+// BAD — brute-force vulnerable login with no rate limiting
+app.post("/login", async (req, res) => {
+  const user = await User.findByEmail(req.body.email);
+  if (user && user.password === req.body.password) {
+    // also: plaintext comparison!
+    req.session.userId = user.id;
+    res.json({ success: true });
+  }
+});
+
+// GOOD — rate limited, constant-time comparison, bcrypt
+import rateLimit from "express-rate-limit";
+import bcrypt from "bcrypt";
+
+const loginLimiter = rateLimit({ windowMs: 15 * 60 * 1000, max: 10 });
+
+app.post("/login", loginLimiter, async (req, res) => {
+  const user = await User.findByEmail(req.body.email);
+  const match =
+    user && (await bcrypt.compare(req.body.password, user.passwordHash));
+  if (!match) return res.status(401).json({ error: "Invalid credentials" });
+  req.session.userId = user.id;
+  res.json({ success: true });
+});
+```
+
+**What to check:**
+
+- Rate limiting on login, password reset, and email verification endpoints
+- Account lockout after N failed attempts (or CAPTCHA)
+- Session tokens regenerated after privilege escalation (login, role change)
+- Sessions invalidated on logout (server-side session store, not just clearing the cookie)
+- JWT expiry enforced — `exp` claim checked
+
+---
+
+### A08: Software and Data Integrity Failures
+
+- Deserialisation of untrusted data (pickle in Python, Java ObjectInputStream)
+- CI/CD pipelines that pull dependencies without checksum verification
+- Auto-update mechanisms that don't verify signatures
+
+---
+
+### A09: Security Logging and Monitoring Failures
+
+**What to check:**
+
+- Failed login attempts logged (email, IP, timestamp — NOT the attempted password)
+- Admin actions logged (who did what, when)
+- Logs don't contain sensitive data (passwords, full credit card numbers, session tokens)
+- Errors logged with enough context to investigate (request ID, user ID if available)
+
+---
+
+### A10: Server-Side Request Forgery (SSRF)
+
+Relevant when the application fetches URLs provided by the user.
+
+```js
+// BAD — user can point the server to internal services
+app.post("/fetch-preview", async (req, res) => {
+  const html = await fetch(req.body.url).then((r) => r.text());
+  res.json({ html });
+  // Payload: http://169.254.169.254/latest/meta-data/ (AWS metadata endpoint)
+});
+
+// GOOD — validate URL is on an allowlist of external domains
+const ALLOWED_HOSTS = ["example.com", "another-trusted.com"];
+const url = new URL(req.body.url);
+if (!ALLOWED_HOSTS.includes(url.hostname)) {
+  return res.status(400).json({ error: "URL not allowed" });
+}
+```
+
+---
+
+## Mass Assignment
+
+**Web frameworks that auto-bind request body to model fields:**
+
+```js
+// BAD — user can set any field, including isAdmin
+const user = new User(req.body);
+await user.save();
+
+// GOOD — whitelist only the fields you intend to update
+const { name, email } = req.body;
+const user = new User({ name, email });
+await user.save();
+```
+
+```python
+# BAD — Flask-SQLAlchemy mass assignment
+user = User(**request.json)
+
+# GOOD
+user = User(
+    name=request.json['name'],
+    email=request.json['email'],
+)
+```
+
+---
+
+## JWT-specific issues
+
+```js
+// BAD — algorithm confusion attack: accept 'none' or HS256 when expecting RS256
+jwt.verify(token, publicKey); // default options accept alg: none
+
+// GOOD — explicitly specify allowed algorithms
+jwt.verify(token, publicKey, { algorithms: ["RS256"] });
+
+// BAD — not checking expiry
+const decoded = jwt.decode(token); // decode does NOT verify signature or expiry
+
+// GOOD — always verify, never just decode in auth paths
+const decoded = jwt.verify(token, secret);
+```
+
+---
+
+## File upload security
+
+```js
+// BAD — no type checking, stores user filename directly
+app.post("/upload", upload.single("file"), (req, res) => {
+  fs.renameSync(req.file.path, `/uploads/${req.file.originalname}`);
+});
+
+// GOOD — validate MIME type, generate safe filename
+const ALLOWED_TYPES = ["image/jpeg", "image/png", "image/webp"];
+if (!ALLOWED_TYPES.includes(req.file.mimetype)) {
+  return res.status(400).json({ error: "File type not allowed" });
+}
+const safeFilename = `${crypto.randomUUID()}${path.extname(req.file.originalname)}`;
+fs.renameSync(req.file.path, `/uploads/${safeFilename}`);
+```
+
+---
+
+## Severity mapping for review findings
+
+| Finding                        | OWASP category | Severity                   |
+| ------------------------------ | -------------- | -------------------------- |
+| SQL injection                  | A03            | P0 — block merge           |
+| Auth bypass                    | A07            | P0 — block merge           |
+| IDOR (missing ownership check) | A01            | P0 — block merge           |
+| Hardcoded secret               | A02            | P0 — block merge           |
+| Plaintext password storage     | A02            | P0 — block merge           |
+| Missing rate limiting on login | A07            | P1                         |
+| XSS (unescaped output)         | A03            | P0–P1 depending on context |
+| Missing CSRF                   | A01            | P1                         |
+| Sensitive data in logs         | A09            | P1                         |
+| No JWT algorithm restriction   | A02            | P1                         |
+| Missing security headers       | A05            | P2                         |
+| Mass assignment                | A08            | P0–P1 depending on fields  |

package/content/plugins/reviews/skills/agileflow-pr-reviewer/workflows/review-pr.md

@@ -0,0 +1,153 @@
+# Workflow: Review PR
+
+**Triggers:** "review this PR", "review my changes", "check my code", user shares a diff or file changes
+
+**Goal:** Produce a structured, prioritised review with findings across all dimensions and a clear merge recommendation.
+
+---
+
+## Inputs needed
+
+| Input                     | Required  | How to get it                                         |
+| ------------------------- | --------- | ----------------------------------------------------- |
+| The diff or changed files | Yes       | Paste, file paths, or `git diff` output               |
+| PR description / context  | Preferred | Paste; or ask "What does this change do?"             |
+| Target branch             | No        | Usually `main` — ask if branching strategy is unusual |
+| Change type               | Preferred | Feature, bugfix, refactor, chore                      |
+
+---
+
+## Steps
+
+### Step 1: Read the change
+
+Read every changed file fully. Don't skim. Build a complete picture of:
+
+- What the change is doing
+- What it's removing
+- What assumptions the author is making
+
+### Step 2: Read the surrounding context
+
+For each changed file:
+
+- Read 20–30 lines above and below each change for context
+- Check if there is an existing test file for this module
+- Check if there are related files that should also have changed but didn't
+
+### Step 3: Check the PR description
+
+If no PR description was provided, ask:
+
+- "What does this change do and why?"
+- "Is there a ticket or issue this corresponds to?"
+
+A PR without a description is harder to review — flag this as a P3 finding.
+
+### Step 4: Run dimension checks
+
+Work through each dimension from `references/review-checklist.md` that applies to this change:
+
+| Change type                | Dimensions to run                    |
+| -------------------------- | ------------------------------------ |
+| New feature with endpoints | Security, Logic, Tests, API Contract |
+| Bug fix                    | Logic, Tests                         |
+| Refactor                   | Logic, Tests, Breaking Changes       |
+| Auth-related change        | Security (full), Logic, Tests        |
+| Database migration         | API Contract, Breaking Changes       |
+| Dependency update          | Security (A06), Tests                |
+| UI / frontend only         | Logic, Tests, style                  |
+
+### Step 5: Collect all findings
+
+List every finding as you go. Don't filter yet — capture everything.
+
+### Step 6: Assign severities
+
+Review the collected findings and assign P0–P3 using the severity table in the SKILL.md.
+
+When in doubt between severities:
+
+- If it can cause data loss, a security breach, or a crash in production → P0
+- If it will cause incorrect behaviour → P1
+- If it should be tested but isn't → P2
+- If it's a style or readability concern → P3
+
+### Step 7: Sort and present findings
+
+Present findings in P0 → P3 order. For each:
+
+```
+[P{level}] {DIMENSION} — {One-line summary}
+  File: {filename}, line {N}
+  Issue: {What is wrong and why it matters}
+  Fix: {Concrete suggestion}
+```
+
+### Step 8: Write the summary block
+
+Always end with a structured summary:
+
+```
+─────────────────────────────────────
+REVIEW SUMMARY
+─────────────────────────────────────
+Files reviewed: {N}
+Lines changed: +{added} / -{removed}
+Findings: {P0 count} P0, {P1 count} P1, {P2 count} P2, {P3 count} P3
+
+VERDICT: {APPROVE | REQUEST CHANGES | NEEDS DISCUSSION}
+
+{If REQUEST CHANGES: list the must-fix items}
+{If APPROVE: one sentence on what looks good}
+{If NEEDS DISCUSSION: what the design question is}
+─────────────────────────────────────
+```
+
+### Step 9: Offer next step
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Review complete — {verdict}. {N} findings.",
+  "header": "What next",
+  "multiSelect": false,
+  "options": [
+    {"label": "Fix the P0 and P1 issues now (Recommended)", "description": "I'll work through each finding and write the corrected code"},
+    {"label": "Explain a specific finding in more detail", "description": "Tell me which finding number you want me to expand on"},
+    {"label": "Write the missing tests", "description": "I'll add tests for the uncovered paths flagged in P2 findings"},
+    {"label": "Re-review after fixes", "description": "Once you've addressed the findings, share the updated diff for a re-review"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+## Special handling for large PRs (> 400 LOC)
+
+If the diff is very large:
+
+1. Flag this as a P3 finding: "PRs over ~400 LOC are harder to review thoroughly and increase merge risk — consider splitting."
+2. Ask if there are sections to prioritise: "This is a large change. Shall I focus on the security-sensitive parts first?"
+3. Review in passes: security first, then logic, then tests, then style
+
+---
+
+## Fallbacks
+
+**If AskUserQuestion is unavailable:**
+
+Present the next step as a numbered list:
+
+```
+Review complete — REQUEST CHANGES. 3 findings.
+
+To continue:
+1. Fix the 3 findings now — I'll write the corrected code for each
+2. Explain finding #1 (SQL injection) in more detail
+3. Write the missing tests flagged in finding #3
+4. Mark as done and re-review the updated diff
+
+Reply with a number or describe what you want to do next.
+```

package/content/plugins/reviews/skills/agileflow-pr-reviewer/workflows/security-review.md

@@ -0,0 +1,177 @@
+# Workflow: Security Review
+
+**Triggers:** user asks for a security review, change touches auth/login/permissions/file-upload/payments/database queries, or a P0 security finding was flagged in a standard review
+
+**Goal:** Systematic, OWASP-anchored security review of the changed code, producing a prioritised list of vulnerabilities with concrete fixes.
+
+---
+
+## When to run a full security review
+
+Run this workflow (instead of the standard review) when:
+
+- Change touches authentication or session management
+- Change adds or modifies API endpoints that handle user data
+- Change adds file upload, import, or download functionality
+- Change modifies database queries or ORM calls
+- Change handles payments, billing, or financial data
+- Change adds cryptographic operations (hashing, signing, encryption)
+- Change modifies CORS, security headers, or cookie settings
+- Change introduces a third-party integration with data exchange
+
+---
+
+## Inputs needed
+
+| Input                 | Required  | How to get it                                               |
+| --------------------- | --------- | ----------------------------------------------------------- |
+| Changed files         | Yes       | Paste or file paths                                         |
+| What the change does  | Yes       | PR description or ask                                       |
+| Framework / language  | Yes       | Detect from code                                            |
+| Auth mechanism in use | Preferred | Ask: "How does this app handle auth? JWT, sessions, OAuth?" |
+
+---
+
+## Steps
+
+### Step 1: Identify the attack surface
+
+Map what user-controlled input enters the system in this change:
+
+- HTTP request body, query params, headers
+- File uploads
+- URLs fetched by the server
+- Database record fields updated by the user
+- External webhook payloads
+
+For each input, trace where it goes:
+
+- Into a SQL query?
+- Into a shell command?
+- Into an HTML response?
+- Into a file path?
+- Into a redirect URL?
+
+### Step 2: Run the OWASP Top 10 checklist
+
+Work through each category from `references/security-patterns.md` that is relevant to this change:
+
+| Category                      | Check if change touches...                                 |
+| ----------------------------- | ---------------------------------------------------------- |
+| A01 Broken Access Control     | Endpoints returning or modifying user-specific resources   |
+| A02 Cryptographic Failures    | Password storage, tokens, encryption                       |
+| A03 Injection                 | Database queries, shell commands, HTML output, URL parsing |
+| A04 Insecure Design           | Auth flows, rate limiting, account recovery                |
+| A05 Security Misconfiguration | CORS, headers, debug settings                              |
+| A07 Auth Failures             | Login, logout, session management, JWTs                    |
+| A08 Integrity Failures        | Deserialisation, file processing                           |
+| A09 Logging Failures          | What gets logged — is sensitive data included?             |
+| A10 SSRF                      | Server fetching user-provided URLs                         |
+
+### Step 3: Check for mass assignment
+
+For any endpoint that takes a request body and uses it to create or update a database record:
+
+1. What fields does the model have?
+2. What fields are in the request body?
+3. Are there fields in the model that should NEVER be user-settable (isAdmin, role, balance, ownerId)?
+4. Is the code whitelisting only the intended fields?
+
+### Step 4: Check for information disclosure
+
+- Do error messages reveal internal paths, table names, or stack traces?
+- Do 404 and 401 responses behave identically for "not found" vs "not authorised" (to prevent enumeration)?
+- Is debug mode or verbose error mode enabled in any code path?
+
+### Step 5: Verify dependency security
+
+If the change adds or updates packages:
+
+- Note the packages added
+- Flag any known-vulnerable packages (CVE lookup if possible)
+- Check that crypto-related packages are well-maintained
+
+### Step 6: Check the test coverage for security paths
+
+Security paths that MUST have explicit tests:
+
+- Authenticated endpoint with no token → 401
+- Authenticated endpoint with another user's resource ID → 403 or 404
+- Input with SQL injection payload → not executed as SQL
+- File upload with wrong MIME type → rejected
+
+If any of these are missing, add them as P2 findings.
+
+### Step 7: Produce findings
+
+Use the same format as the standard review, but add the OWASP category reference:
+
+```
+[P0] SECURITY (A03 - Injection) — SQL Injection in user search endpoint
+  File: src/api/users.js, line 34
+  Issue: User-provided 'search' query param concatenated into SQL:
+         `SELECT * FROM users WHERE name LIKE '%${search}%'`
+         An attacker can inject: "'; DROP TABLE users; --"
+  Fix: Use parameterised query: db.query("SELECT * FROM users WHERE name LIKE $1", [`%${search}%`])
+  Test: Add test: POST /api/users/search with payload "'; SELECT 1 --" should return 400 or safe empty result
+
+[P0] SECURITY (A01 - Broken Access Control) — Missing ownership check on GET /api/documents/:id
+  File: src/api/documents.js, line 18
+  Issue: Any authenticated user can fetch any document by guessing its ID
+  Fix: Add check: if (doc.ownerId !== req.user.id) return res.status(403).json({ error: 'Forbidden' })
+  Test: Add test: authenticated request for another user's document should return 403
+```
+
+### Step 8: Summary and recommendation
+
+```
+─────────────────────────────────────
+SECURITY REVIEW SUMMARY
+─────────────────────────────────────
+Attack surface reviewed:
+  - {N} API endpoints
+  - {M} database operations
+  - {K} user-input paths
+
+OWASP categories checked: A01, A02, A03, A07 (others N/A for this change)
+
+Vulnerabilities found:
+  P0: {N} — must fix before merge
+  P1: {N} — strong recommendation to fix
+  P2: {N} — missing security tests
+
+VERDICT: {APPROVE | REQUEST CHANGES}
+─────────────────────────────────────
+```
+
+---
+
+## Threat modelling quick questions
+
+If the security review is for a new feature (not a bugfix), run through these:
+
+1. **Who is the adversary?** Unauthenticated users? Authenticated users acting maliciously? Internal bad actors?
+2. **What is the most valuable asset?** User PII? Financial data? Admin capabilities?
+3. **What is the worst-case scenario if this code has a vulnerability?**
+4. **What would a malicious user try first?**
+
+Use these to prioritise which attack vectors to investigate most thoroughly.
+
+---
+
+## Fallbacks
+
+**If AskUserQuestion is unavailable:**
+
+Present findings as a numbered list and ask:
+
+```
+Security review complete. {N} findings.
+
+1. Fix all P0 vulnerabilities now — I'll write the corrected code
+2. Explain how to exploit finding #1 (for understanding, not exploitation)
+3. Write the missing security tests
+4. Proceed to standard review after security fixes
+
+Reply with a number.
+```