lastlight 0.1.15 → 0.2.1

package/skills/security-feedback/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: security-feedback
+description: Process a maintainer's comment on a security scan-summary issue — break selected findings out into individual actionable issues, or record accepted risks / false positives in SECURITY.md.
+version: 2.0.0
+tags: [github, security, feedback]
+---
+
+# Security Feedback
+
+A maintainer commented on a `security`-labelled issue — almost always a per-run
+**security scan summary** (one issue per scan, a task-list of findings). Based on
+the comment, either:
+
+- **Break selected findings into individual issues** (each can later feed `build`). Primary flow.
+- **Record a suppression** in `SECURITY.md` (accepted risk / false positive).
+- Reply for discussion, or ignore noise.
+
+The parent issue's grammar is the contract defined in
+`skills/security-review/references/issue-format.md`. This skill is staged into its
+own workspace and **cannot read that file**, so it carries its own copy of the
+row/severity regex below — **if you change the grammar, update both in lockstep.**
+
+## Context
+
+- `context.repo` — `owner/name`
+- `context.issueNumber` — the security summary issue (parent)
+- `context.commentBody` — the triggering comment
+- `context.sender` — the commenter's GitHub login
+
+The parent body is not passed — fetch it at step 1.
+
+## 1. Fetch and parse the parent issue
+
+`github_get_issue({ owner, repo, issue_number: issueNumber })`.
+
+**Version check.** The body MUST start with `<!-- lastlight-security-scan-version: 1 -->`.
+If the marker is missing or the version isn't `1`, reply: "Unknown scan-summary
+format — this skill is at version 1 but the parent reports a different version.
+Ask the maintainer to re-run `@last-light security-review`." Do not parse further.
+
+**Parse each finding row** with this canonical regex (all three states):
+
+```
+/^- \[([ x])\] <!-- item:(\d+) fp:([0-9a-f]{8,}) --> (?:~~)?\*\*(.+?)\*\* — `([^`]+):(\d+)` \(([a-z][a-z0-9-]*) · `([^`]+)`\)(?:~~ → #(\d+))?$/m
+```
+
+Captures: `checkbox` (` `/`x`), `item`, `fp`, `title`, `file`, `line`, `tool`,
+`rule`, and `subIssueNumber` (only when already broken out). Derive per row:
+
+| Derived | Definition |
+|---------|------------|
+| `alreadyBrokenOut` | `subIssueNumber != null` — turned into a sub-issue on a prior run |
+| `userTicked` | `checkbox === "x" && !alreadyBrokenOut` — the maintainer ticked the box, selecting it |
+
+`userTicked` is the primary selection signal; `alreadyBrokenOut` rows are never
+re-selected regardless of checkbox state.
+
+**Severity** comes from the nearest preceding section header (tolerating a
+trailing truncation suffix like `(showing first 7 of 25)`):
+
+```
+/^### (🔴|🟠|🟡|🟢) (Critical|High|Medium|Low) \((\d+)\)(?:\s.*)?$/m
+```
+
+Map Critical/High/Medium/Low → `p0-critical`/`p1-high`/`p2-medium`/`p3-low`.
+
+**Parse the `<details>` block** after each row (starts `<details><summary>Details</summary>`,
+ends `</details>`): the fenced block → `snippet` + `language`; paragraphs between
+the fence and `**Suggested fix:**` → `explanation`; text after `**Suggested fix:**`
+→ `suggestedFix`.
+
+Store each finding as `{ item, fp, title, file, line, tool, rule, severity,
+language, snippet, explanation, suggestedFix, userTicked, alreadyBrokenOut, subIssueNumber? }`.
+
+## 2. Classify the comment intent
+
+Pick the single best-fit bucket:
+
+- **create-issues** — break selected findings out. Signals: bare `@last-light
+  create issues` (defaults to ticked), "create issues for…", "make issues for…",
+  "break out…", "file sub-issues for…", "create an issue for items 1, 3".
+- **accept-risk** — accept a finding's risk. Signals: "accept-risk:", "we know
+  about this", "won't fix", "accepted".
+- **false-positive** — not real. Signals: "false-positive:", "not a vulnerability",
+  "not applicable".
+- **reopen** — re-evaluate a suppressed finding. Signals: "reopen", "re-evaluate".
+- **discuss** — a question or conversation about the findings.
+- **ignore** — noise (thanks, unrelated remark).
+
+`accept-risk` / `false-positive` / `reopen` MUST name a specific finding via
+`item N` / `item: N` — fall through to `discuss` if unresolved.
+
+## 3. Act
+
+### create-issues
+
+1. **Resolve the selection** (first match wins):
+   - **`ticked` / `checked` / `selected`** → every `userTicked` finding. Preferred UX.
+   - **Default (no qualifier)** → treat as `ticked`. If no rows are ticked, reply:
+     ```
+     No rows are ticked. Tick the checkboxes on the findings you want broken out, then comment again — or use one of:
+     - `@last-light create issues for the criticals`
+     - `@last-light create issues for items 1, 3, 5`
+     - `@last-light create issues for all`
+     ```
+   - `all` / `every` → every parsed finding regardless of tick state.
+   - `criticals` / `the criticals` / `p0-critical` → every `p0-critical` (same for
+     highs/mediums/lows). A count in the comment ("5 criticals") is ignored.
+   - `items N, M` / `item N` → specific 1-based item numbers from `<!-- item:N -->`.
+
+   In every form, silently drop `alreadyBrokenOut` findings and mention them in the
+   summary. If the selection is empty, reply:
+   ```
+   No findings matched `{selection text}`. This scan has: {nC} critical, {nH} high, {nM} medium, {nL} low. Ticked: {nTicked}. Already broken out: {nDone}.
+   ```
+   and create nothing. If the form is unrecognised (ambiguous), ask for clarification — don't guess.
+
+2. **For each selected finding**, `github_create_issue` using the sub-issue body
+   template in [references/templates.md](references/templates.md). Record each new
+   `subIssueNumber` against its `item`.
+
+3. **Rewrite the parent body.** For every finding just broken out, transition its
+   row to **broken-out**:
+   ```
+   - [x] <!-- item:N fp:FP --> ~~**TITLE** — `FILE:LINE` (TOOL · `RULE`)~~ → #SUBISSUE
+   ```
+   (checkbox `[x]`, title+location wrapped in `~~…~~`, ` → #SUBISSUE` appended).
+   Match by `item:N`. Do **not** touch rows that weren't selected, even if ticked.
+   Preserve all other content byte-for-byte. `github_update_issue`.
+
+4. **Post a summary comment** on the parent:
+   ```
+   Created {N} sub-issue(s) at @{sender}'s request:
+
+   - #{subN1} — {title 1} (item {item1})
+   …
+
+   {if any skipped}: Skipped {M} item(s) already broken out: items {list}.
+
+   Comment `@last-light build` on any sub-issue to start a fix.
+   ```
+
+### accept-risk / false-positive
+
+1. Resolve the target by `item N`; fall through to `discuss` if absent/unknown.
+2. Extract the reason (text after the first `:`, trimmed; "no reason given" if absent).
+3. `github_clone_repo`. Read `SECURITY.md`; create from the scaffold in
+   [references/templates.md](references/templates.md) if missing.
+4. Append a row to the matching table (accepted risks OR false positives) per the
+   template.
+5. Commit on branch `security/feedback-{parentIssueNumber}-{shortFingerprint}`,
+   push, and open a PR titled `security: record {accept-risk|false-positive} for {shortFingerprint}`.
+6. Comment on the parent: `Opened PR #{prNumber} to record this in SECURITY.md.
+   Once merged, this finding will be suppressed in future scans.`
+7. Do **not** tick the task-list checkbox — that marker is reserved for "broken out to sub-issue".
+
+### reopen
+
+Reply: "To re-evaluate this finding, run `@last-light security-review` — the next
+scan re-picks it up if `SECURITY.md` has been updated." Do not modify `SECURITY.md`.
+
+### discuss
+
+Reply conversationally using the finding's `<details>` block (risk, tool, suggested
+fix). Don't modify `SECURITY.md` or create sub-issues.
+
+### ignore
+
+Take no action.
+
+## Tool usage
+
+GitHub operations via `github_*` MCP tools only — never `gh` CLI, `curl`, or raw HTTP.

package/skills/security-feedback/references/templates.md

@@ -0,0 +1,77 @@
+# security-feedback templates
+
+## Sub-issue body (create-issues)
+
+`github_create_issue` with `title` = the finding's `title` (exactly as parsed, no
+prefix/suffix), `labels` = `["security", severity]` (e.g. `["security",
+"p0-critical"]`), and this body:
+
+````markdown
+<!-- fp:{fingerprint} -->
+<!-- parent-security-scan: #{parentIssueNumber} -->
+
+Broken out from security scan #{parentIssueNumber} on {today's date} at @{sender}'s request.
+
+**File**: `{file}:{line}`
+**Tool**: {tool} · `{rule}`
+**Severity**: {severity}
+
+```{language}
+{snippet}
+```
+
+{explanation}
+
+## Suggested fix
+
+{suggestedFix}
+
+---
+
+_To build a fix for this finding, comment `@last-light build` on this issue._
+````
+
+## SECURITY.md scaffold (accept-risk / false-positive)
+
+Create this if `SECURITY.md` is missing, then append the row:
+
+```markdown
+# SECURITY.md
+
+This file configures the Last Light security scanner for this repository.
+
+## Tool configuration
+
+| Tool | Severity floor |
+|------|---------------|
+| npm-audit | medium |
+| semgrep | medium |
+| gitleaks | high |
+| claude | medium |
+
+## Accepted risks
+
+Findings in this table are known risks the maintainers have explicitly accepted.
+The scanner will not re-file issues for these findings.
+
+| Fingerprint | Title | Reason | Date | Issue |
+|-------------|-------|--------|------|-------|
+
+## False positives
+
+Findings in this table have been classified as not real security issues.
+The scanner will not re-file issues for these findings.
+
+| Fingerprint | Title | Reason | Date | Issue |
+|-------------|-------|--------|------|-------|
+```
+
+Appended row (to whichever table matches the intent):
+
+| Column | Value |
+|--------|-------|
+| Fingerprint | First 16 hex chars of the finding's `fp` |
+| Title | Finding's `title` |
+| Reason | Extracted reason (text after the first `:`; "no reason given" if absent) |
+| Date | Today's date (YYYY-MM-DD, UTC) |
+| Issue | `#{parentIssueNumber}` |

package/skills/security-review/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: security-review
+description: Diff-scoped security review of SDLC concerns GitHub's scanners miss — workflow/CI hardening, auth changes, secret handling, supply-chain churn. Files one dated summary issue with a task-list of findings. Use on a security cron or when asked to scan a repo.
+version: 2.0.0
+tags: [github, security, review]
+---
+
+# Security Review
+
+Review **what changed in the repo since the last scan** with a security lens,
+focused on SDLC concerns that GitHub's built-in scanners (Dependabot, Code
+Scanning, Secret Scanning) and Renovate don't cover. File **one summary issue
+per run**, dated, containing a GitHub task list of any findings. Honour
+`SECURITY.md` to suppress accepted risks and false positives.
+
+This is **not** a general vulnerability scanner. It does not run `npm audit`
+(Dependabot does). It does not run `semgrep --config auto` over the whole tree
+(Code Scanning does). It looks at the diff since the prior scan and surfaces what
+humans introduced — CI hardening, auth changes, secret handling in new code,
+supply-chain churn.
+
+The summary issue's structure is the machine-parsed contract a maintainer's
+later comment is processed against (the `security-feedback` skill). It is defined
+in **[references/issue-format.md](references/issue-format.md)** — follow it
+exactly when composing the issue (§9).
+
+## Context
+
+- `context.repo` — `owner/name` to scan
+- `context.deliverSlackSummary` — if true, output a one-line Slack summary as the final response
+- `context.issueDir` — directory for the run summary file (e.g. `.lastlight/security-<date>`)
+
+## Procedure
+
+### 1. Clone, find the prior-scan anchor, read SECURITY.md
+
+1. Clone the target repo via `github_clone_repo`.
+2. **Prior scan anchor.** Query issues labelled `security-scan` (open OR closed),
+   newest first. Read the latest one's body for the
+   `<!-- lastlight-security-scan-ts: ... -->` comment and use that ISO-8601
+   timestamp as `priorScanTs`. No prior scan issue → `priorScanTs = now - 30 days`
+   (bootstrap floor — keeps the first run finite).
+3. Read `SECURITY.md` at the repo root (if present): per-tool severity floors
+   (default `medium`; skip `low`/`info`), the accepted-risks table, and the
+   false-positives table (both keyed by finding fingerprint).
+
+### 1.5. Compute the changeset
+
+Most weeks the diff is dominated by Renovate/Dependabot churn — strip it so the
+scope is what humans wrote.
+
+1. `git log --since="${priorScanTs}" --pretty=format:'%H|%an|%ae|%s'`.
+2. Drop a commit when **either**: author email matches
+   `*[bot]@users.noreply.github.com` and name is `dependabot[bot]` /
+   `renovate[bot]` / `github-actions[bot]`; OR the subject starts with
+   `chore(deps)`, `chore(deps-dev)`, `build(deps)`, `build(deps-dev)`, `fix(deps)`.
+3. Accumulate changed files from the surviving commits
+   (`git diff-tree --no-commit-id --name-only -r ${sha}`) into a deduped
+   `changedFiles` set.
+4. Drop entries that are **only** lockfiles (`package-lock.json`, `pnpm-lock.yaml`,
+   `yarn.lock`, `bun.lockb`, `Gemfile.lock`, `poetry.lock`, `uv.lock`,
+   `Cargo.lock`, `composer.lock`) — catches lockfile changes mixed into human commits.
+5. Build `commitsReviewed` = surviving commits as `{ shortSha, subject }` (used in the scope note).
+
+**Early exit.** If `changedFiles` is empty after filtering, **stop**: run no
+scanner, create no issue, emit no Slack message. Write the run summary file (§10)
+recording "no relevant changes since prior scan" and return.
+
+### 2. Ensure labels exist
+
+`github_create_label` for each (idempotent — ignore 422):
+
+| Label | Color | Purpose |
+|-------|-------|---------|
+| `security` | `ee0701` | Any security-related issue |
+| `security-scan` | `fbca04` | The per-run summary issue |
+| `p0-critical` | `b60205` | Severity |
+| `p1-high` | `d93f0b` | Severity |
+| `p2-medium` | `fbca04` | Severity |
+| `p3-low` | `0e8a16` | Severity |
+
+### 3. Run change-scoped scanners
+
+Three sources, all narrowed to the changeset. Do **not** run `npm audit` or
+`semgrep --config auto .` over the whole tree (covered elsewhere; the noise
+drowns the signal).
+
+- **Gitleaks (commit range):**
+  `gitleaks detect --source . --log-opts="--since=${priorScanTs}" --report-format json --report-path /tmp/gitleaks.json`
+  — secrets introduced in the new history.
+- **Semgrep (changed files only):**
+  `semgrep --config auto --json $(printf -- '--include=%s ' "${changedFiles[@]}")`
+  — only files that changed; far less noise.
+- **Claude SDLC review** — the unique value-add. Read `git diff ${priorScanTs}..HEAD`
+  plus the current contents of changed files against the checklist below. Each
+  match becomes a finding with `tool: "claude"` and the §4 severity.
+
+  - **GitHub Actions / CI** (`.github/workflows/*.yml`): actions pinned by
+    floating ref (`@main`/`@master`/`@v1`) not a commit SHA; `pull_request_target`
+    that checks out the PR head; missing top-level/job `permissions:` block;
+    `${{ secrets.* }}` interpolated into shell/`run:`/echo where it can land in
+    logs; untrusted PR body/title/branch interpolated into a `run:` block.
+  - **Dockerfile / compose**: base images on floating tags (no digest) introduced
+    here; new `RUN curl … | sh` / `wget … | bash`; new `--privileged`/`--cap-add`,
+    removed `security_opt`/`read_only` hardening; new host-exposed ports without need.
+  - **Auth / authorization**: modified middleware, route guards, role checks, CORS,
+    JWT verification, OAuth handlers, webhook signature verification (HMAC compare,
+    `crypto.timingSafeEqual` replaced with `===`).
+  - **Secret handling in new code**: new `process.env.*` reads whose value flows
+    into a log or HTTP response; new code logging Authorization headers/cookies/tokens;
+    hardcoded key/URL-shaped literals gitleaks missed.
+  - **Shell exec on attacker-influenced args**: new `execSync`/`exec`/`spawn` where
+    any argument is non-static (concatenation, interpolation, request-derived).
+  - **Supply-chain churn** (`package.json` diff): **new** top-level
+    `dependencies`/`devDependencies` entries (not version bumps — filtered at §1.5);
+    flag package name + publisher, higher severity for typosquat-shaped names;
+    removed integrity controls (`npm ci` → `npm install`, dropped `--ignore-scripts`
+    or provenance flags).
+  - **Release / publish flows**: changes to publish scripts, `npm publish`, release
+    CI steps, signing keys — anything touching what users download.
+
+  If the only changes are docs/tests/unrelated config and none of the above
+  applied, the run legitimately has **no findings** — proceed to §8.
+
+### 4. Normalize findings
+
+Convert each to: `{ fingerprint, severity, tool, rule, file, line, title,
+language, snippet, explanation, suggestedFix }`.
+
+- `fingerprint` = `sha1(tool + ":" + rule + ":" + file + ":" + 3-line-context)`, lowercase hex.
+- `severity` ∈ `p0-critical | p1-high | p2-medium | p3-low`.
+- `tool` ∈ `npm-audit | semgrep | gitleaks | claude` (lowercase, hyphenated).
+- `rule` = tool-native id, as-is. `file` = repo-relative, forward slashes.
+- `line` = 1-based; `0` when not line-scoped. `title` = one line, no backticks/asterisks.
+
+Severity mapping: npm-audit critical/high/moderate/low → p0/p1/p2/p3;
+semgrep ERROR/WARNING/INFO → p1/p2/p3; gitleaks (all) → p1-high;
+claude critical/high/medium/low → p0/p1/p2/p3.
+
+### 5. Apply severity floor
+
+Drop findings below the SECURITY.md floor (default `medium` → drops `p3-low`).
+
+### 6. Filter accepted risks / false positives
+
+Drop findings whose fingerprint prefix (first 16 hex chars) appears in the
+SECURITY.md accepted-risks or false-positives tables.
+
+### 7. Sort and cap
+
+Sort by `(severity rank p0<p1<p2<p3, then file asc, then line asc)`.
+
+The issue body has a hard 65,536-char GitHub limit. Cap: keep **ALL** `p0-critical`
+and **ALL** `p1-high`; keep at most **10** of `p2-medium`+`p3-low` combined (the
+first 10 after the sort). Assign 1-based `item` numbers top-to-bottom across the
+**kept** findings. `overflow` = survived-filtering minus kept; surface it in the
+overflow note.
+
+The cap intentionally puts no ceiling on critical/high — if a misconfigured
+scanner emits hundreds of highs and the body still overflows, raise the
+`SECURITY.md` floor or tune the scanner's rule severities (fix at the source, not
+by hiding real findings).
+
+### 8. Early exit: no findings
+
+If the filtered-and-capped list is empty, **do not** create the summary issue.
+Write the run summary file (§10) recording why and return **silently** — no Slack
+message. The cron is intentionally low-noise: only actual findings surface.
+
+### 9. Compose and create the summary issue
+
+Render the body per [references/issue-format.md](references/issue-format.md) and
+`github_create_issue` with `title: Security scan — {YYYY-MM-DD}` (UTC),
+`labels: ["security", "security-scan"]`. Record `summaryIssueNumber`. Do **not**
+touch prior `security-scan` issues — each scan is a point-in-time snapshot.
+
+### 10. Write the run summary file
+
+Write `{issueDir}/security-summary.md`:
+
+```markdown
+# Security Scan Summary — {repo}
+
+**Date**: {YYYY-MM-DD}
+**Prior scan anchor**: {priorScanTs} (issue #{priorScanIssueNumber} or "bootstrap floor")
+**Commits reviewed**: {N} (after filtering Renovate/Dependabot/lockfile-only)
+**Changed files**: {nFiles}
+**Summary issue**: #{summaryIssueNumber} (or "none — no findings")
+
+**Scanner raw counts**: gitleaks: {n}, semgrep: {n}, claude: {n}
+**After severity floor**: {n}
+**After SECURITY.md filtering**: {n} (filed)
+**Suppressed**: {n} (accepted: {nA}, false-positive: {nFP})
+{if overflow > 0}: **Overflow**: {overflow} lower-severity findings omitted (cap: ALL critical/high + first 10 medium/low)
+```
+
+On a §1.5 early exit, still write the file and state `**Early exit**: no human
+commits since prior scan`.
+
+### 11. Slack summary (optional)
+
+If `context.deliverSlackSummary` is true, output as the final response:
+
+- **With findings:**
+  ```
+  *Security scan: {repo}* — {n} findings filed in #{summaryIssueNumber} ({N} commits since {priorScanDate})
+  Critical: {nC} · High: {nH} · Medium: {nM} · Low: {nL}
+  ```
+- **No findings** (scanners ran clean) or **§1.5 early exit** → emit nothing;
+  silence matches the cron's low-noise design. The run summary file still records
+  what was reviewed.
+
+Otherwise output the run summary file contents as the final response.