@yaawn/workflow 0.0.0-stage → 0.3.1

package/agents/skills/yaawn-implement-plan/scripts/worktrees.ts

@@ -0,0 +1,431 @@
+import { execFile, execFileSync } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+import { uncommittedChangesAsync } from "./targets.js";
+
+// Shared by yaawn-implement-plan (creates one git worktree per issue) and
+// yaawn-verify-executed-plan (checks it verifies in the issue's worktree).
+//
+// Layout: the project root holds a bare `.git` repository, the main working
+// copy is a normal checkout at `<project>/main`, and every issue worktree is
+// a sibling of it at `<project>/yaawn-<issue>-<slug>`.
+
+export type WorktreeCheckStatus = "ok" | "warn" | "fail";
+
+export interface WorktreeCheck {
+  status: WorktreeCheckStatus;
+  message: string;
+}
+
+export interface WorktreeLayout {
+  issue: number;
+  mainCopy: string;
+  registered: Iterable<string>;
+  currentToplevel: string;
+  // Resolved by branch (yaawn/<issue>), not by the title slug — the slug in
+  // the directory name is for humans only.
+  ownWorktree?: string | null;
+}
+
+export interface WorktreeEntry {
+  path: string;
+  branch: string | null;
+  bare: boolean;
+}
+
+export interface AheadBehind {
+  ahead: number;
+  behind: number;
+}
+
+// How the main copy's HEAD relates to its upstream branch.
+export type MainCopyState =
+  | { kind: "up-to-date" }
+  | { kind: "ahead"; ahead: number }
+  | { kind: "behind"; behind: number }
+  | { kind: "diverged"; ahead: number; behind: number };
+
+export type MainCopyCheck =
+  | { ok: true; state: MainCopyState }
+  | { ok: false; reason: string };
+
+export type MainCopySync =
+  | { ok: true; state: MainCopyState; updated: boolean }
+  | { ok: false; reason: string };
+
+const worktreePrefix = "worktree ";
+const branchPrefix = "branch refs/heads/";
+const maxSlugLength = 40;
+const fallbackMainCopyName = "main";
+const fallbackDefaultBranches = ["main", "master"];
+
+const aheadBehindPattern = /^(\d+)\s+(\d+)$/;
+const execFileAsync = promisify(execFile);
+
+export const branchName = (issue: number): string => `yaawn/${issue}`;
+
+export function git(args: string[]): string {
+  return execFileSync("git", args, {
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+// --- names
+
+function assertIssueNumber(issue: number): void {
+  if (!Number.isSafeInteger(issue) || issue <= 0) {
+    throw new Error(`issue must be a positive integer, got ${issue}`);
+  }
+}
+
+// Only [a-z0-9-] survives, so the title can never add `..`, `/`, or
+// whitespace to a path.
+export function titleSlug(title: string): string {
+  return title
+    .normalize("NFKD")
+    .replace(/\p{M}/gu, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, maxSlugLength)
+    .replace(/-+$/, "");
+}
+
+export function worktreeName(issue: number, title: string): string {
+  assertIssueNumber(issue);
+  const slug = titleSlug(title);
+  return slug ? `yaawn-${issue}-${slug}` : `yaawn-${issue}`;
+}
+
+// --- porcelain
+
+function entryFromBlock(lines: string[]): WorktreeEntry | null {
+  const pathLine = lines.find((line) => line.startsWith(worktreePrefix));
+  if (pathLine === undefined) return null;
+  const branchLine = lines.find((line) => line.startsWith(branchPrefix));
+  return {
+    path: pathLine.slice(worktreePrefix.length),
+    branch:
+      branchLine === undefined ? null : branchLine.slice(branchPrefix.length),
+    bare: lines.includes("bare"),
+  };
+}
+
+export function entriesFromPorcelain(porcelain: string): WorktreeEntry[] {
+  return porcelain
+    .split(/\n\s*\n/)
+    .map((block) => entryFromBlock(block.split("\n")))
+    .filter((entry): entry is WorktreeEntry => entry !== null);
+}
+
+export function worktreesFromPorcelain(porcelain: string): string[] {
+  return entriesFromPorcelain(porcelain).map((entry) => entry.path);
+}
+
+// git lists the bare repository first, whichever worktree it runs in.
+export function isBareLayout(porcelain: string): boolean {
+  return entriesFromPorcelain(porcelain)[0]?.bare === true;
+}
+
+// git names the bare repository after the project root; a `.git` suffix is
+// stripped defensively.
+export function projectRootFromPorcelain(porcelain: string): string {
+  const [first] = worktreesFromPorcelain(porcelain);
+  if (!first) throw new Error("git worktree list returned no worktree");
+  return path.basename(first) === ".git" ? path.dirname(first) : first;
+}
+
+// The main working copy is the registered worktree on the default branch.
+export function mainCopyFromPorcelain(
+  porcelain: string,
+  defaultBranches: string[] = fallbackDefaultBranches,
+): string {
+  const checkouts = entriesFromPorcelain(porcelain).filter(
+    (entry) => !entry.bare,
+  );
+  const onDefault = defaultBranches
+    .map((branch) => checkouts.find((entry) => entry.branch === branch))
+    .find((entry) => entry !== undefined);
+  return (
+    onDefault?.path ??
+    path.join(projectRootFromPorcelain(porcelain), fallbackMainCopyName)
+  );
+}
+
+export function branchWorktreeFromPorcelain(
+  porcelain: string,
+  branch: string,
+): string | null {
+  const checkout = entriesFromPorcelain(porcelain).find(
+    (entry) => !entry.bare && entry.branch === branch,
+  );
+  return checkout?.path ?? null;
+}
+
+export function worktreePathFor(
+  projectRoot: string,
+  issue: number,
+  title: string,
+): string {
+  return path.join(projectRoot, worktreeName(issue, title));
+}
+
+// --- git
+
+export const listPorcelain = (): string => git(["worktree", "list", "--porcelain"]);
+
+export const currentToplevel = (): string =>
+  git(["rev-parse", "--show-toplevel"]).trim();
+
+// The bare repository's HEAD names the default branch it was cloned with.
+function bareHeadBranch(): string | null {
+  try {
+    const commonDir = git([
+      "rev-parse",
+      "--path-format=absolute",
+      "--git-common-dir",
+    ]).trim();
+    const head = git([
+      "--git-dir",
+      commonDir,
+      "symbolic-ref",
+      "--quiet",
+      "--short",
+      "HEAD",
+    ]).trim();
+    return head || null;
+  } catch {
+    return null;
+  }
+}
+
+export function defaultBranches(): string[] {
+  const head = bareHeadBranch();
+  return [...new Set([...(head ? [head] : []), ...fallbackDefaultBranches])];
+}
+
+export function usesBareLayout(): boolean {
+  return isBareLayout(listPorcelain());
+}
+
+export function worktreePath(issue: number, title: string): string {
+  return worktreePathFor(
+    projectRootFromPorcelain(listPorcelain()),
+    issue,
+    title,
+  );
+}
+
+// The branch's existing checkout wins over the title-derived path, so a
+// relaunch resumes the earlier worktree even after the issue was renamed.
+export function laneWorktreePath(issue: number, title: string): string {
+  const porcelain = listPorcelain();
+  return (
+    branchWorktreeFromPorcelain(porcelain, branchName(issue)) ??
+    worktreePathFor(projectRootFromPorcelain(porcelain), issue, title)
+  );
+}
+
+export function registeredWorktrees(): Set<string> {
+  return new Set(worktreesFromPorcelain(listPorcelain()));
+}
+
+const normalized = (worktree: string): string => path.resolve(worktree);
+
+const samePath = (left: string, right: string): boolean =>
+  normalized(left) === normalized(right);
+
+export function runsInOwnWorktree(issue: number, title: string): boolean {
+  return samePath(worktreePath(issue, title), currentToplevel());
+}
+
+// --- classification
+
+function checkOwnWorktree(own: string, toplevel: string): WorktreeCheck {
+  return samePath(own, toplevel)
+    ? { status: "ok", message: `verifying in the issue's worktree ${own}` }
+    : {
+        status: "fail",
+        message: `run verification in the issue's worktree ${own}, not in ${toplevel}`,
+      };
+}
+
+function checkMainCopy(
+  issue: number,
+  mainCopy: string,
+  toplevel: string,
+): WorktreeCheck {
+  return samePath(mainCopy, toplevel)
+    ? {
+        status: "warn",
+        message: `#${issue} has no git worktree of its own — verifying the main copy`,
+      }
+    : {
+        status: "fail",
+        message: `#${issue} has no git worktree of its own — run verification in the main copy ${mainCopy}, not in ${toplevel}`,
+      };
+}
+
+export function classifyWorktree(layout: WorktreeLayout): WorktreeCheck {
+  const { issue, mainCopy, registered, ownWorktree, currentToplevel } = layout;
+  const own =
+    ownWorktree != null &&
+    [...registered].some((worktree) => samePath(worktree, ownWorktree))
+      ? ownWorktree
+      : null;
+  return own !== null
+    ? checkOwnWorktree(own, currentToplevel)
+    : checkMainCopy(issue, mainCopy, currentToplevel);
+}
+
+export function checkWorktree(issue: number): WorktreeCheck {
+  const porcelain = listPorcelain();
+  return classifyWorktree({
+    issue,
+    mainCopy: mainCopyFromPorcelain(porcelain, defaultBranches()),
+    registered: worktreesFromPorcelain(porcelain),
+    currentToplevel: currentToplevel(),
+    ownWorktree: branchWorktreeFromPorcelain(porcelain, branchName(issue)),
+  });
+}
+
+// --- main copy sync
+
+// Parses `git rev-list --left-right --count HEAD...@{u}`: "<ahead>\t<behind>".
+export function parseAheadBehind(output: string): AheadBehind | null {
+  const match = aheadBehindPattern.exec(output.trim());
+  if (match === null) return null;
+  return { ahead: Number(match[1]), behind: Number(match[2]) };
+}
+
+export function classifyMainCopyState({
+  ahead,
+  behind,
+}: AheadBehind): MainCopyState {
+  if (ahead > 0 && behind > 0) return { kind: "diverged", ahead, behind };
+  if (behind > 0) return { kind: "behind", behind };
+  if (ahead > 0) return { kind: "ahead", ahead };
+  return { kind: "up-to-date" };
+}
+
+const commits = (count: number): string =>
+  count === 1 ? "1 commit" : `${count} commits`;
+
+export function describeMainCopyState(state: MainCopyState): string {
+  switch (state.kind) {
+    case "up-to-date":
+      return "main copy is up to date";
+    case "ahead":
+      return `main copy is ${commits(state.ahead)} ahead — lanes start from it`;
+    case "behind":
+      return `main copy is ${commits(state.behind)} behind — the launch will bring it up to date`;
+    case "diverged":
+      return `main copy has diverged (${state.ahead} ahead, ${state.behind} behind) — reconcile it by hand before launching`;
+  }
+}
+
+// git's stderr may echo a remote URL with credentials in it.
+function redactedGitError(error: unknown): string {
+  const stderr =
+    typeof error === "object" && error !== null && "stderr" in error
+      ? String(error.stderr)
+      : "";
+  const line = stderr
+    .split("\n")
+    .map((text) => text.trim())
+    .find(Boolean);
+  return line ? `: ${line.replace(/\/\/[^/\s@]+@/g, "//***@")}` : "";
+}
+
+// Never waits for a credential prompt: an unattended launch would hang.
+async function gitAsync(args: string[]): Promise<string> {
+  const { stdout } = await execFileAsync("git", args, {
+    encoding: "utf-8",
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+  });
+  return stdout;
+}
+
+async function hasUpstream(): Promise<boolean> {
+  try {
+    await gitAsync(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function mainCopyAheadBehind(): Promise<AheadBehind | null> {
+  try {
+    return parseAheadBehind(
+      await gitAsync(["rev-list", "--left-right", "--count", "HEAD...@{u}"]),
+    );
+  } catch {
+    return null;
+  }
+}
+
+// Fetches the main copy's upstream and compares; it never changes the main copy.
+export async function fetchMainCopy(): Promise<MainCopyCheck> {
+  if (!(await hasUpstream())) {
+    return {
+      ok: false,
+      reason:
+        "main copy's branch has no upstream — set one with `git branch --set-upstream-to`",
+    };
+  }
+  try {
+    await gitAsync(["fetch", "--quiet"]);
+  } catch (error) {
+    return {
+      ok: false,
+      reason: `could not fetch the main copy's upstream — remote unreachable${redactedGitError(error)}`,
+    };
+  }
+  const counts = await mainCopyAheadBehind();
+  return counts === null
+    ? { ok: false, reason: "could not compare the main copy with its upstream" }
+    : { ok: true, state: classifyMainCopyState(counts) };
+}
+
+export function blockedUpdateReason(behind: number): string {
+  return `main copy is ${commits(behind)} behind and uncommitted changes block the update — commit or stash them first`;
+}
+
+async function uncommittedChangesFailure(behind: number): Promise<string | null> {
+  try {
+    return (await uncommittedChangesAsync()).trim()
+      ? blockedUpdateReason(behind)
+      : null;
+  } catch {
+    return "could not list uncommitted changes in the main copy";
+  }
+}
+
+async function fastForwardMainCopy(): Promise<string | null> {
+  try {
+    await gitAsync(["merge", "--ff-only", "--quiet", "@{u}"]);
+    return null;
+  } catch (error) {
+    return `could not fast-forward the main copy${redactedGitError(error)}`;
+  }
+}
+
+// Fails closed: the main copy is only fast-forwarded when it is behind and
+// clean; any unknown state stops the launch before a worktree exists.
+export async function syncMainCopy(): Promise<MainCopySync> {
+  const check = await fetchMainCopy();
+  if (!check.ok) return check;
+  const { state } = check;
+  if (state.kind === "diverged") {
+    return { ok: false, reason: describeMainCopyState(state) };
+  }
+  if (state.kind !== "behind") return { ok: true, state, updated: false };
+  const failure =
+    (await uncommittedChangesFailure(state.behind)) ??
+    (await fastForwardMainCopy());
+  return failure === null
+    ? { ok: true, state, updated: true }
+    : { ok: false, reason: failure };
+}

package/agents/skills/yaawn-owasp-security/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: yaawn-owasp-security
+description: "Background security lens based on the OWASP Top 10:2025. Read silently when proposing designs, plans, or code — bake mitigations in autonomously. Only escalate to the developer when a risk cannot be mitigated without their input. Use when: creating an implementation plan (/yaawn-create-plan), grilling a design (/yaawn-grill-design), implementing a plan (/yaawn-implement-plan), reviewing code for security risks, or when the user asks to make something secure, check for vulnerabilities, harden, or audit code."
+user-invocable: false
+---
+
+# OWASP Top 10:2025 Security Lens
+
+Applies the [OWASP Top 10:2025](https://top10.owasp.org/2025/) as a background security lens across the yaawn plan pipeline. This is **not** a checklist to grill through. The agent reads the relevant risks silently, bakes mitigations into every design decision, plan step, and line of code it proposes — and only surfaces a risk to the developer when it cannot resolve it on its own.
+
+This skill **complements** the pipeline skills. Load it alongside `/yaawn-create-plan`, `/yaawn-grill-design`, or `/yaawn-implement-plan`.
+
+## How It Works
+
+```
+Agent reads the issue / design / code being proposed
+        │
+        ▼
+Match against the routing table below → load ONLY the relevant reference files
+        │
+        ▼
+Silently check the proposal against each loaded risk
+        │
+   ┌────┴────┐
+   ▼         ▼
+Covered    Cannot mitigate alone
+   │         │
+   ▼         ▼
+Bake the   Escalate with a recommended
+mitigation  mitigation — never ask an
+into the    open-ended "how do you want
+proposal    to handle security?"
+```
+
+## Routing Table
+
+Read the issue, design decisions, or code being proposed. Match what it touches against the keywords below. Load **only** the reference files that match. Each reference file is self-contained — it has the OWASP risk details, design-phase guidance, and implementation checks for that risk.
+
+| What the plan or code touches                                                                              | Keywords to match                                                                                                | Load                                                                                                |
+| ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| New API endpoints, routes, permissions, roles, data access by ID, cross-domain calls, CORS, redirects      | endpoint, route, permission, role, authorize, IDOR, ownership, CORS, redirect, URL routing                       | [a01-broken-access-control.md](./references/a01-broken-access-control.md)                           |
+| New config, env vars, dependencies, services, error messages, cookies, headers, deployment, debug          | config, env, cookie, header, CSP, HSTS, debug, sample, default, hardening, secret                                | [a02-security-misconfiguration.md](./references/a02-security-misconfiguration.md)                   |
+| Adding dependencies, CI/CD changes, build scripts, Docker images, package registries                       | dependency, npm, package, CI, pipeline, action, Docker, image, registry, lockfile, SBOM                          | [a03-software-supply-chain-failures.md](./references/a03-software-supply-chain-failures.md)         |
+| Passwords, tokens, encryption, hashing, randomness, sensitive data storage, TLS, keys                      | password, token, encrypt, hash, random, salt, key, TLS, HSTS, PII, sensitive data, credential                    | [a04-cryptographic-failures.md](./references/a04-cryptographic-failures.md)                         |
+| User input, database queries, HTML rendering, file uploads, shell commands, redirects, ORM                 | input, query, SQL, ORM, render, XSS, upload, file, eval, shell, command, sanitize, escape, validate              | [a05-injection.md](./references/a05-injection.md)                                                   |
+| New trust boundaries, auth flows, payment flows, business logic, tenant isolation, client-side enforcement | trust boundary, auth flow, payment, business logic, tenant, isolation, client-side, misuse case, abuse case      | [a06-insecure-design.md](./references/a06-insecure-design.md)                                       |
+| Login, registration, sessions, password reset, MFA, JWT, SSO, account enumeration                          | login, signin, register, session, password reset, MFA, 2FA, JWT, SSO, token, brute force, lockout                | [a07-authentication-failures.md](./references/a07-authentication-failures.md)                       |
+| External data sources, webhooks, deserialization, auto-updates, plugins, CI/CD integrity                   | webhook, callback, external data, deserialize, serialize, auto-update, plugin, extension, signature, checksum    | [a08-software-data-integrity-failures.md](./references/a08-software-data-integrity-failures.md)     |
+| Any code path handling security events, errors, or transactions                                            | log, audit, alert, monitor, security event, auth failure, access denied, validation failure                      | [a09-security-logging-alerting-failures.md](./references/a09-security-logging-alerting-failures.md) |
+| Error handling, multi-step transactions, resource cleanup, rate limiting, concurrency                      | error, exception, catch, throw, rollback, transaction, finally, cleanup, rate limit, throttle, concurrency, race | [a10-mishandling-exceptional-conditions.md](./references/a10-mishandling-exceptional-conditions.md) |
+
+### Always consider
+
+These risks apply broadly — load them whenever the plan or code has the corresponding shape, even if no specific keyword matches:
+
+- **A06 (Insecure Design)** — load whenever the proposal introduces a trust boundary, a security-critical flow, or client-side enforcement of a security control.
+- **A09 (Logging)** — load whenever the code handles authentication, authorization, input validation, or transactions. These events must be logged.
+- **A10 (Exception Handling)** — load whenever the code has error paths, multi-step operations, or resource management. Errors must fail closed and not leak details.
+
+### Loading strategy
+
+- **Plan creation / grilling:** scan the issue and design decisions, load 2–4 matching references, apply silently when proposing decisions.
+- **Implementation:** scan the step being implemented, load 1–3 matching references, verify code against the implementation checks before marking done.
+- **Code review:** scan the diff, load matching references, check the changed code.
+- **Don't load all 10.** A plan that adds a search endpoint needs A01, A05, A09, and A10 — not A04 or A07.
+
+## The 10 Risks at a Glance
+
+| #   | Risk                                   | One-line summary                                                                          |
+| --- | -------------------------------------- | ----------------------------------------------------------------------------------------- |
+| A01 | Broken Access Control                  | Users can act outside their intended permissions — enforce deny-by-default on the server. |
+| A02 | Security Misconfiguration              | Unnecessary features, default credentials, missing headers, verbose errors.               |
+| A03 | Software Supply Chain Failures         | Vulnerable, unmaintained, or untrusted dependencies and build tooling.                    |
+| A04 | Cryptographic Failures                 | Weak algorithms, missing encryption, hard-coded keys, poor randomness.                    |
+| A05 | Injection                              | Untrusted input executed as commands — SQL, OS, XSS, LDAP, expression language.           |
+| A06 | Insecure Design                        | Missing or ineffective security controls in the architecture and business logic.          |
+| A07 | Authentication Failures                | Weak credentials, no MFA, session fixation, brute-force exposure.                         |
+| A08 | Software or Data Integrity Failures    | Unverified updates, unsigned artifacts, insecure deserialization.                         |
+| A09 | Security Logging and Alerting Failures | Missing logs for security events, no alerting, sensitive data in logs.                    |
+| A10 | Mishandling of Exceptional Conditions  | Errors leak data, fail open, crash the system, or corrupt state.                          |
+
+## Rules
+
+- **Silent by default.** The agent applies security autonomously. The developer should not be asked about risks the agent can handle.
+- **Deny by default.** When in doubt, the secure option wins. The burden of proof is on the insecure option.
+- **Bake, don't bolt on.** Mitigations go into the design and plan from the start — not as a post-hoc review layer.
+- **Escalate with a recommendation.** When escalation is unavoidable, present the risk and a recommended mitigation. The developer confirms or adjusts — they are not asked to solve it from scratch.
+- **Never log or commit secrets.** This applies to the agent's own output — no credentials, tokens, or keys in plan files, decision logs, code, or issue comments.
+- **Record security decisions in the decision log.** When the agent bakes a mitigation into a proposal, log it briefly: `- Security (Axx): <what was done> — <why>`. One line. This keeps the plan auditable without bloating the conversation.
+
+## Gotchas
+
+- **A06 Insecure Design is the meta-risk.** If the proposed design itself is insecure (missing trust boundaries, client-side-only enforcement, no threat model for the flow), no amount of careful coding fixes it. The agent should revise the design proposal, not just the implementation. Only escalate if the design constraint comes from the developer.
+- **A03 and A08 overlap.** A03 covers the supply chain (dependencies, build tools, CI/CD). A08 covers integrity verification (signatures, deserialization, auto-updates). The agent checks both when a proposal adds a dependency.
+- **A09 is easy to skip silently.** The agent should proactively include logging for security-relevant events in its proposals — not wait to be asked. Auth failures, access denials, and input validation failures are always in scope.
+- **A10 is new in 2025.** Error handling is a security control: fail closed, don't leak stack traces, roll back partial transactions. The agent bakes this into every proposal that touches error paths.
+- **Don't over-escalate.** If the agent can propose a secure default and move on, it should. Escalation is for genuine decisions, not for every risk that crosses its desk.
+
+## Done When
+
+Before finishing a plan, grill, implementation step, or code review with this lens loaded:
+
+- [ ] Every reference matching the routing table was loaded and checked against the proposal
+- [ ] Mitigations are baked into the proposal itself — not listed as follow-up actions
+- [ ] Each baked mitigation is recorded in the decision log as `- Security (Axx): <what was done> — <why>`
+- [ ] Anything the agent cannot mitigate is escalated with a recommended mitigation

package/agents/skills/yaawn-owasp-security/references/a01-broken-access-control.md

@@ -0,0 +1,58 @@
+# A01:2025 — Broken Access Control
+
+**Rank:** #1 (100% of applications tested had some form of broken access control)
+
+Access control enforces policy such that users cannot act outside of their intended permissions. Failures typically lead to unauthorized information disclosure, modification or destruction of all data, or performing a business function outside the user's limits.
+
+## You are vulnerable if
+
+- Violation of the principle of least privilege (deny by default) — access available to anyone
+- Bypassing access control checks by modifying the URL (parameter tampering, force browsing), internal application state, or the HTML page
+- Permitting viewing or editing someone else's account by providing its unique identifier (insecure direct object references / IDOR)
+- APIs with missing access controls for POST, PUT, and DELETE
+- Elevation of privilege — acting as a user without being logged in, or gaining admin access
+- Metadata manipulation — replaying or tampering with JWT tokens, cookies, or hidden fields to elevate privileges
+- CORS misconfiguration allowing API access from unauthorized or untrusted origins
+- Force browsing (guessing URLs) to authenticated or privileged pages
+
+## How to prevent (OWASP)
+
+- Access control is only effective in trusted server-side code or serverless APIs
+- Except for public resources, **deny by default**
+- Implement access control mechanisms once and reuse them throughout the application; minimize CORS usage
+- Enforce record ownership rather than allowing users to CRUD any record
+- Enforce unique business limit requirements via domain models
+- Disable web server directory listing; ensure file metadata (e.g. `.git`) and backup files are not in web roots
+- Log access control failures; alert admins on repeated failures
+- Implement rate limits on API and controller access
+- Invalidate stateful session identifiers on logout; use short-lived JWTs
+- Use well-established toolkits or patterns for simple, declarative access controls
+- Include functional access control in unit and integration tests
+
+## Design phase — silently check and bake in
+
+- Default to deny: new routes, endpoints, and data access are restricted unless the proposal explicitly makes them public.
+- If the proposal reads or modifies records by ID, bake in an ownership check.
+- If the proposal adds an API endpoint, bake in server-side authorization — not just authentication.
+- If the proposal crosses a domain boundary, bake in the access control at the target domain's public API.
+- If the proposal touches CORS, URL routing, or redirects, bake in a review step.
+- If the proposal introduces client-side access control (hiding buttons, route guards), flag it as insufficient and bake in the server-side equivalent.
+
+## Design phase — escalate when
+
+The proposal requires a permission model the agent cannot infer (e.g. a new role hierarchy, custom RBAC rules) — propose a default role model and ask for confirmation.
+
+## Implementation checks
+
+- Every new endpoint/action checks authorization server-side — not just authentication
+- Record access by ID includes an ownership check
+- New routes, endpoints, and data access are denied by default unless explicitly public
+- Privileged URLs return 403/404 for unauthorized users — no force-browsing
+- CORS is not widened to untrusted origins
+- Access control failures are logged
+- Rate limits are in place on new API endpoints
+- Tests cover: unauthorized access denied, cross-user access denied, privilege escalation blocked
+
+## Key CWEs
+
+CWE-200, CWE-201, CWE-352 (CSRF), CWE-639 (IDOR), CWE-862 (Missing Authorization), CWE-863 (Incorrect Authorization), CWE-918 (SSRF), CWE-22 (Path Traversal), CWE-601 (Open Redirect)

package/agents/skills/yaawn-owasp-security/references/a02-security-misconfiguration.md

@@ -0,0 +1,56 @@
+# A02:2025 — Security Misconfiguration
+
+**Rank:** #2 (moved up from #5; 100% of applications tested had some form of misconfiguration)
+
+Security misconfiguration is when a system, application, or cloud service is set up incorrectly from a security perspective, creating vulnerabilities.
+
+## You are vulnerable if
+
+- Missing appropriate security hardening across any part of the application stack, or improperly configured permissions on cloud services
+- Unnecessary features are enabled or installed (ports, services, pages, accounts, testing frameworks, privileges)
+- Default accounts and their passwords are still enabled and unchanged
+- Error handling reveals stack traces or overly informative error messages to users
+- For upgraded systems, the latest security features are disabled or not configured securely
+- Excessive prioritization of backward compatibility leading to insecure configuration
+- Security settings in application servers, frameworks, libraries, databases are not set to secure values
+- The server does not send security headers or directives, or they are not set to secure values
+
+## How to prevent (OWASP)
+
+- Implement a repeatable hardening process for fast, easy deployment of locked-down environments
+- Use a minimal platform without unnecessary features, components, documentation, or samples
+- Review and update configurations as part of patch management; review cloud storage permissions
+- Use a segmented application architecture with separation between components or tenants
+- Send security directives to clients (security headers)
+- Automate verification of configurations and settings in all environments
+- Proactively add central configuration to intercept excessive error messages
+- Use identity federation, short-lived credentials, or role-based access — never embed static keys or secrets in code, configuration files, or pipelines
+
+## Design phase — silently check and bake in
+
+- New env vars or config values: bake in secure defaults and document them.
+- New error messages: bake in generic user-facing messages with detailed logs.
+- New dependencies or services: bake in a hardening step (remove defaults, disable debug, set secure headers).
+- Any secret the proposal needs: bake in environment variable or secret manager usage — never hard-coded.
+- Cookie settings: bake in `Secure`, `HttpOnly`, `SameSite`.
+- Security headers: if the proposal touches HTTP responses, bake in CSP, HSTS, X-Content-Type-Options.
+
+## Design phase — escalate when
+
+The proposal requires infrastructure configuration the agent cannot make (e.g. cloud IAM, CDN settings) — list it as a manual step in the plan.
+
+## Implementation checks
+
+- No default credentials in any environment, config file, or seed data
+- No unnecessary features, debug endpoints, or sample data in the build
+- Security headers are set (CSP, HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy)
+- Error responses do not include stack traces, file paths, or system details
+- No secrets in source code, config files, or committed environment files
+- Secrets come from environment variables or a secret manager
+- Cookie settings: `Secure`, `HttpOnly`, `SameSite` set appropriately
+- Directory listing is disabled
+- `.git`, `.env`, and backup files are not accessible from the web root
+
+## Key CWEs
+
+CWE-16 (Configuration), CWE-611 (XXE), CWE-260 (Password in Configuration File), CWE-547 (Hard-coded Constants), CWE-489 (Active Debug Code), CWE-942 (Permissive Cross-domain Policy)