@igorlau/dotagents 1.0.21 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. package/README.md +65 -65
  2. package/THIRD_PARTY_NOTICES.md +101 -6
  3. package/dist/build-info.json +1 -1
  4. package/dist/catalog.js +3 -3
  5. package/dist/cli.js +1 -1
  6. package/dist/commands.js +9 -8
  7. package/dist/manifest.js +8 -1
  8. package/dist/paths.js +0 -4
  9. package/dist/targets.js +3 -9
  10. package/dist/wizard.js +1 -1
  11. package/package.json +5 -3
  12. package/{plugin/rules → rules}/comments.upstream.json +1 -1
  13. package/{plugin/rules → rules}/ponytail.md +1 -1
  14. package/{plugin/rules → rules}/ponytail.upstream.json +1 -1
  15. package/{plugin/rules → rules}/writing.md +1 -2
  16. package/{plugin/rules → rules}/writing.upstream.json +1 -1
  17. package/{plugin/scaffold → scaffold}/AGENTS.md.tmpl +1 -1
  18. package/{plugin/skills → skills}/dot-code-review/SKILL.md +2 -0
  19. package/{plugin/skills → skills}/dot-code-review/UPSTREAM.json +1 -1
  20. package/skills/dot-code-review/references/finding-classes.md +33 -0
  21. package/{plugin/skills → skills}/dot-comments/UPSTREAM.json +1 -1
  22. package/{plugin/skills → skills}/dot-commit/SKILL.md +0 -2
  23. package/skills/dot-correct/UPSTREAM.json +8 -0
  24. package/{plugin/skills → skills}/dot-debug/UPSTREAM.json +1 -1
  25. package/{plugin/skills → skills}/dot-grilling/UPSTREAM.json +2 -2
  26. package/{plugin/skills → skills}/dot-handoff/UPSTREAM.json +1 -1
  27. package/{plugin/skills → skills}/dot-implement/SKILL.md +2 -2
  28. package/{plugin/skills → skills}/dot-plan/SKILL.md +3 -1
  29. package/{plugin/skills → skills}/dot-roadmap/SKILL.md +7 -4
  30. package/skills/dot-security-audit/SKILL.md +87 -0
  31. package/skills/dot-security-audit/UPSTREAM.json +8 -0
  32. package/skills/dot-security-audit/references/AI-AND-LLM.md +83 -0
  33. package/skills/dot-security-audit/references/ATTACK-CLASSES.md +130 -0
  34. package/skills/dot-security-audit/references/CLIENT-SIDE.md +83 -0
  35. package/skills/dot-security-audit/references/CLOUD-AND-DEPLOYMENT.md +86 -0
  36. package/skills/dot-security-audit/references/DATA-ISOLATION-AND-LIFECYCLE.md +84 -0
  37. package/skills/dot-security-audit/references/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -0
  38. package/skills/dot-security-audit/references/MEMORY-SAFETY-AND-BINARY.md +101 -0
  39. package/skills/dot-security-audit/references/PROTOCOLS-RPC-AND-MESSAGING.md +81 -0
  40. package/skills/dot-security-audit/references/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -0
  41. package/skills/dot-security-audit/references/SUPPLY-CHAIN-AND-RELEASE.md +73 -0
  42. package/skills/dot-security-audit/references/WEB-PROTOCOL-AND-AUTH.md +105 -0
  43. package/skills/dot-security-changes/SKILL.md +68 -0
  44. package/{plugin/skills → skills}/dot-testing/UPSTREAM.json +1 -1
  45. package/skills/dot-ui-review/SKILL.md +79 -0
  46. package/skills/dot-ui-review/UPSTREAM.json +8 -0
  47. package/skills/dot-ux-review/SKILL.md +50 -0
  48. package/skills/dot-ux-review/UPSTREAM.json +8 -0
  49. package/skills/dot-ux-review/references/web-interface-guidelines.md +191 -0
  50. package/{plugin/skills/dot-stack-review → skills/dot-walkthrough-branch}/SKILL.md +9 -30
  51. package/skills/dot-walkthrough-branch/references/layers.md +38 -0
  52. package/{plugin/skills/dot-stack-review → skills/dot-walkthrough-branch}/scripts/page.mjs +39 -10
  53. package/skills/dot-walkthrough-changes/SKILL.md +62 -0
  54. package/skills/dot-writing-for-agents/UPSTREAM.json +8 -0
  55. package/plugin/.claude-plugin/plugin.json +0 -10
  56. package/plugin/agents/dot-implementer.md +0 -27
  57. package/plugin/agents/dot-reviewer.md +0 -44
  58. package/plugin/agents/dot-tester.md +0 -25
  59. package/plugin/hooks/check.mjs +0 -118
  60. package/plugin/hooks/hooks.json +0 -54
  61. package/plugin/hooks/rules.mjs +0 -27
  62. package/plugin/skills/dot-correct/UPSTREAM.json +0 -8
  63. package/plugin/skills/dot-correct/agents/openai.yaml +0 -5
  64. package/plugin/skills/dot-debug/agents/openai.yaml +0 -3
  65. package/plugin/skills/dot-flow/SKILL.md +0 -105
  66. package/plugin/skills/dot-flow/agents/openai.yaml +0 -5
  67. package/plugin/skills/dot-flow/references/fix-round.md +0 -64
  68. package/plugin/skills/dot-flow/references/inline.md +0 -9
  69. package/plugin/skills/dot-grilling/agents/openai.yaml +0 -3
  70. package/plugin/skills/dot-handoff/agents/openai.yaml +0 -5
  71. package/plugin/skills/dot-roadmap/agents/openai.yaml +0 -5
  72. package/plugin/skills/dot-stack-review/agents/openai.yaml +0 -5
  73. package/plugin/skills/dot-writing-for-agents/UPSTREAM.json +0 -8
  74. package/plugin/skills/dot-writing-for-agents/agents/openai.yaml +0 -3
  75. /package/{plugin/rules → rules}/code-style.md +0 -0
  76. /package/{plugin/rules → rules}/comments.md +0 -0
  77. /package/{plugin/rules → rules}/core.md +0 -0
  78. /package/{plugin/scaffold → scaffold}/.claude/settings.json.tmpl +0 -0
  79. /package/{plugin/scaffold → scaffold}/.editorconfig.tmpl +0 -0
  80. /package/{plugin/scaffold → scaffold}/.gitattributes.tmpl +0 -0
  81. /package/{plugin/scaffold → scaffold}/CLAUDE.md.tmpl +0 -0
  82. /package/{plugin/skills → skills}/dot-code-review/references/maintainability.md +0 -0
  83. /package/{plugin/skills → skills}/dot-comments/SKILL.md +0 -0
  84. /package/{plugin/skills → skills}/dot-correct/SKILL.md +0 -0
  85. /package/{plugin/skills → skills}/dot-debug/SKILL.md +0 -0
  86. /package/{plugin/skills → skills}/dot-debug/references/loops.md +0 -0
  87. /package/{plugin/skills → skills}/dot-debug/scripts/hitl-loop.template.sh +0 -0
  88. /package/{plugin/skills → skills}/dot-docs-writing/SKILL.md +0 -0
  89. /package/{plugin/skills → skills}/dot-docs-writing/references/formatting.md +0 -0
  90. /package/{plugin/skills → skills}/dot-docs-writing/references/global-and-accessible.md +0 -0
  91. /package/{plugin/skills → skills}/dot-docs-writing/references/word-list.md +0 -0
  92. /package/{plugin/skills → skills}/dot-grilling/SKILL.md +0 -0
  93. /package/{plugin/skills → skills}/dot-handoff/SKILL.md +0 -0
  94. /package/{plugin/skills → skills}/dot-implement/UPSTREAM.json +0 -0
  95. /package/{plugin/skills → skills}/dot-implement/references/typescript.md +0 -0
  96. /package/{plugin/skills → skills}/dot-plan/UPSTREAM.json +0 -0
  97. /package/{plugin/skills → skills}/dot-plan/references/entity-schemas.md +0 -0
  98. /package/{plugin/skills → skills}/dot-roadmap/UPSTREAM.json +0 -0
  99. /package/{plugin/skills → skills}/dot-roadmap/references/wide-refactor.md +0 -0
  100. /package/{plugin/skills → skills}/dot-testing/SKILL.md +0 -0
  101. /package/{plugin/skills → skills}/dot-testing/references/after-implement.md +0 -0
  102. /package/{plugin/skills → skills}/dot-testing/references/http.md +0 -0
  103. /package/{plugin/skills → skills}/dot-testing/references/shared-state.md +0 -0
  104. /package/{plugin/skills → skills}/dot-testing/references/typescript.md +0 -0
  105. /package/{plugin/skills → skills}/dot-writing-for-agents/SKILL.md +0 -0
  106. /package/{plugin/skills → skills}/dot-writing-for-agents/references/pointers.md +0 -0
  107. /package/{plugin/skills → skills}/dot-writing-for-agents/references/skill-mechanics.md +0 -0
  108. /package/{plugin/skills → skills}/dot-writing-for-agents/references/steps.md +0 -0
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "repository": "https://github.com/cursor/plugins",
3
3
  "path": "pstack/skills/no-comments",
4
- "commit": "a5539b15a3d56e04992565aafee2b37051329ce3",
4
+ "commit": "e58dd043600587dbaf58ba315e7f2b38373eeb43",
5
5
  "license": "MIT",
6
6
  "modified": true,
7
7
  "notes": "Merged the policy from pstack/agents/comment-sicko.md into the skill and ran it inline instead of in a subagent. Replaced the /how, /why, and /architect calls with reading the code. Changed the per-flag approval to one approval of the whole report. Rewrote it in neutral wording and renamed it with the dot- prefix."
@@ -52,8 +52,6 @@ Let pre-commit hooks run. When a hook fails, fix the cause, stage the fix, and s
52
52
 
53
53
  Show `git log --oneline` for the commits you created, and list the changes that remain uncommitted. Push only when the user asks.
54
54
 
55
- When the commits finish a task from a `dot-roadmap` roadmap, tick the checkbox of that task in the roadmap's `README.md`, and tell the user.
56
-
57
55
  Done when every group in the plan is committed or skipped, and the user has seen the summary.
58
56
 
59
57
  ## Message format
@@ -0,0 +1,8 @@
1
+ {
2
+ "repository": "https://github.com/cursor/plugins",
3
+ "path": "pstack/skills/correct/SKILL.md",
4
+ "commit": "a5539b15a3d56e04992565aafee2b37051329ce3",
5
+ "license": "MIT",
6
+ "modified": true,
7
+ "notes": "Rewrote the text under rules/writing.md and renamed it with the dot- prefix. Split the levels into architecture, types, a lint rule or check, a test, and docs, and added the approval before a new dependency or a lint configuration change. Left out the rule table in the agent instruction file and the expiry date on exceptions. Merged pstack/skills/principle-encode-lessons-in-structure at the same commit: use only the structural fix when one works, and add an example of the mistake to a docs rule. The commit goes through dot-commit."
8
+ }
@@ -4,5 +4,5 @@
4
4
  "commit": "49dd158d1076134a641b33efb035946536778336",
5
5
  "license": "MIT",
6
6
  "modified": true,
7
- "notes": "Renamed from diagnosing-bugs to debug (frontmatter name and display_name). Added a sentence about the conventions of the repository. Renamed with the dot- prefix. Added the root cause and premise rules to Phase 5, condensed from pstack/skills/principle-fix-root-causes and pstack/skills/principle-attack-the-premise in https://github.com/cursor/plugins at commit a5539b15a3d56e04992565aafee2b37051329ce3 (MIT). Rewrote the text under plugin/rules/writing.md. Moved the ways to build a loop, the bugs that are not deterministic, and the case with no loop to references/loops.md."
7
+ "notes": "Renamed from diagnosing-bugs to debug (frontmatter name and display_name). Added a sentence about the conventions of the repository. Renamed with the dot- prefix. Added the root cause and premise rules to Phase 5, condensed from pstack/skills/principle-fix-root-causes and pstack/skills/principle-attack-the-premise in https://github.com/cursor/plugins at commit a5539b15a3d56e04992565aafee2b37051329ce3 (MIT). Rewrote the text under rules/writing.md. Moved the ways to build a loop, the bugs that are not deterministic, and the case with no loop to references/loops.md."
8
8
  }
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "repository": "https://github.com/mattpocock/skills",
3
3
  "path": "skills/productivity/grilling",
4
- "commit": "49dd158d1076134a641b33efb035946536778336",
4
+ "commit": "5863806dd4e15c63174bee4e7515a4256792ecfa",
5
5
  "license": "MIT",
6
6
  "modified": true,
7
- "notes": "Added a sentence about the conventions of the repository. Renamed with the dot- prefix. Rewrote the text under plugin/rules/writing.md, and replaced the emoji in the round format with text labels."
7
+ "notes": "Added a sentence about the conventions of the repository. Renamed with the dot- prefix. Rewrote the text under rules/writing.md, and replaced the emoji in the round format with text labels."
8
8
  }
@@ -4,5 +4,5 @@
4
4
  "commit": "49dd158d1076134a641b33efb035946536778336",
5
5
  "license": "MIT",
6
6
  "modified": true,
7
- "notes": "Added a sentence about the conventions of the repository. Renamed with the dot- prefix. Rewrote the text under plugin/rules/writing.md."
7
+ "notes": "Added a sentence about the conventions of the repository. Renamed with the dot- prefix. Rewrote the text under rules/writing.md."
8
8
  }
@@ -42,7 +42,7 @@ Check every acceptance criterion one by one. When only an expected failure or a
42
42
 
43
43
  When a hard check or an unexpected failure stays red, or the task or plan turns out wrong (a fact contradicts it, or it needs work outside its scope), stop. Report the check that failed or the fact that conflicts, and propose a change to the task or plan. Keep the task file, the roadmap's requirements and decisions, and the plan as they are until the user agrees, and keep the change inside its scope.
44
44
 
45
- Do not tick the roadmap checkbox. The `dot-commit` skill ticks it after the review step.
45
+ Do not tick the roadmap checkbox. The Gate script of `dot-factory` ticks it, or the user ticks it by hand.
46
46
 
47
47
  Done when the hard checks pass and no unexpected failure remains.
48
48
 
@@ -65,4 +65,4 @@ End with this handoff. The `dot-testing` skill reads its last two fields:
65
65
 
66
66
  Write "none" under a field that has no items.
67
67
 
68
- When `dot-flow` or an agent prompt gave you only the implementation step, stop after the handoff. Otherwise, use the `dot-testing` skill with this handoff now, then suggest the `dot-code-review` skill and the `dot-commit` skill. Leave the commit to the user.
68
+ When an agent prompt gave you only the implementation step, stop after the handoff. Otherwise, use the `dot-testing` skill with this handoff now, then suggest the `dot-code-review` skill and the `dot-commit` skill. Leave the commit to the user.
@@ -7,6 +7,8 @@ description: Plan a change as small, verifiable steps before writing code. Use w
7
7
 
8
8
  A plan turns a request into a sequence of **vertical slices**: each slice is a small change that leaves the system in a state that works and ends on a check you can run.
9
9
 
10
+ **Agent call:** when an agent calls this skill, do not wait for the user in steps 3, 5, and 7, but still produce their content, skip `dot-grilling`, and skip the file write. Mark each unsettled decision as an open question, and return the plan in the shape of step 7.
11
+
10
12
  ## 1. Pin the goal
11
13
 
12
14
  Restate the goal in one or two sentences, and name the **done criterion**: the observable result that tells the user the work is finished (a test that passes, a command's output, a behavior in the UI).
@@ -81,6 +83,6 @@ Show the plan in this shape:
81
83
 
82
84
  Ask the user where to write the plan, and offer `.tmp/plans/<plan-slug>/plan.md` at the repository root as the default. Wait for the user's approval before you change any file.
83
85
 
84
- After the approval, write the plan to that path in the same shape. For a path under `.tmp`, first run `git check-ignore -q .tmp`: if Git does not ignore `.tmp`, stop and tell the user. Do not edit `.gitignore`. Write any other path that the user picks.
86
+ After the approval, write the plan to that path in the same shape. For a path under `.tmp`, first run `git check-ignore -q .tmp/`: if Git does not ignore `.tmp`, stop and tell the user. Do not edit `.gitignore`. Write any other path that the user picks.
85
87
 
86
88
  When the plan changes during the work, update the plan file and say what changed.
@@ -1,14 +1,15 @@
1
1
  ---
2
2
  name: dot-roadmap
3
- description: Turn a grilled plan into a roadmap of phases, each split into self-contained tasks.
3
+ description: Split an existing plan into a roadmap of phases, each split into self-contained tasks. Use when the user asks to split a plan into a roadmap or to break a plan into tasks. Do not use it to write the plan.
4
4
  argument-hint: "Path to the plan, if it is not in this conversation"
5
- disable-model-invocation: true
6
5
  ---
7
6
 
8
7
  # Roadmap
9
8
 
10
9
  A roadmap splits a plan into **phases**, and each phase into **tasks**. A phase ends on a **milestone**: an observable state where the system works and could ship. A task is **self-contained**: a fresh agent session can build it from its file alone, and a reviewer can judge its diff in one session.
11
10
 
11
+ **Agent call:** when an agent calls this skill, skip step 5, write the roadmap to the path that the caller gives (the default of step 6 when it gives none), and return the compact breakdown of step 5.
12
+
12
13
  ## 1. Load the plan
13
14
 
14
15
  Take the plan from the first of these sources that exists:
@@ -40,7 +41,7 @@ Split each phase into tasks. Each task:
40
41
 
41
42
  - Is a **vertical slice**: a narrow but complete path through every layer it needs, verifiable on its own.
42
43
  - Keeps a refactor separate from a behavior change.
43
- - Fits one fresh agent session and one reviewable diff, roughly a few hundred changed lines.
44
+ - Fits one fresh agent session and one reviewable diff of about 300 changed lines or fewer.
44
45
  - Lists its **test cases**: the test names, each with the test file where it belongs, in the order and with the names that the `dot-testing` skill gives. For controller, integration, and end-to-end tests, use `references/http.md` of `dot-testing`. `dot-testing` writes them after `dot-implement`. Write "none" when the task changes no tested behavior.
45
46
  - Declares its **blockers**: the tasks that must be done first, by id (`2.3` is phase 2, task 3). A task without blockers can start now.
46
47
 
@@ -48,6 +49,8 @@ When one mechanical change breaks many call sites at once, read [`references/wid
48
49
 
49
50
  When a bullet of a task's requirements implements a functional requirement (`FR`) or a business rule (`BR`), start the bullet with its ID. User needs (`UN`) and non-negotiables (`NN`) apply to the whole roadmap: they stay in `README.md`, and no task claims them.
50
51
 
52
+ When the plan is one task of about 300 changed lines or fewer, write a one-task roadmap. Otherwise, split it.
53
+
51
54
  Done when every `FR` and `BR` belongs to at least one task or to the roadmap's out-of-scope list, every decision belongs to exactly one task or to that list, and every task has acceptance criteria that can fail.
52
55
 
53
56
  ## 5. Review with the user
@@ -62,7 +65,7 @@ Iterate until the user approves. Write no files before approval.
62
65
 
63
66
  ## 6. Write the roadmap
64
67
 
65
- Write to `.tmp/roadmaps/<roadmap-slug>/` at the repository root. First run `git check-ignore -q .tmp`: if Git does not ignore `.tmp`, stop and tell the user. Do not edit `.gitignore`.
68
+ Write to `.tmp/roadmaps/<roadmap-slug>/` at the repository root. First run `git check-ignore -q .tmp/`: if Git does not ignore `.tmp`, stop and tell the user. Do not edit `.gitignore`.
66
69
 
67
70
  ```
68
71
  .tmp/roadmaps/<roadmap-slug>/
@@ -0,0 +1,87 @@
1
+ ---
2
+ name: dot-security-audit
3
+ description: Security guidance and a vulnerability audit of a whole codebase, a branch, or a path. Use for security questions, focused reviews, vulnerability research, security audits, or pen tests. Run the full audit only when the user asks to audit the codebase or asks for a full or end-to-end security review. Do not use it for the uncommitted changes: use `dot-security-changes`.
4
+ ---
5
+
6
+ # Security audit
7
+
8
+ Find vulnerabilities that cross a real trust boundary. Give the owner the source evidence, the priority, and the smallest fix. This is a defensive, source-first workflow. A candidate with no affected principal, resource, or security result is not a finding.
9
+
10
+ ## Pick the mode
11
+
12
+ - **Guidance mode** (default): for a security question, a focused review, or the triage of one finding. Use only the parts that apply, and write no file.
13
+ - **Full audit mode**: when the user asks to audit or pen-test a codebase, or asks for a full, comprehensive, or end-to-end security review. Follow "Full audit" below.
14
+
15
+ When the request fits both, ask one question before you write a file.
16
+
17
+ ## Run code safely
18
+
19
+ Source reading is read-only. Run a build, a test, or a fixture of the target only inside a sandbox that has all of these controls:
20
+
21
+ - No external network. Use an isolated loopback only when the check needs local traffic.
22
+ - An empty environment, with only the variables that you allow, and a temporary `HOME`.
23
+ - A read-only target. The process writes only to a scratch directory.
24
+ - Low limits for CPU, memory, processes, disk, and time.
25
+
26
+ When the sandbox lacks a control, do not run the target code. Report the check as `needs_validation`, and give a safe plan to run it.
27
+
28
+ Use dummy principals and secrets. Do not probe a deployed endpoint, a shared service, a production identity, or another person's data. Do not install dependencies. Stop at the least effect that proves the defect: a wrong return value, an unauthorized dummy record, or a sanitizer finding.
29
+
30
+ ## Rules for every finding
31
+
32
+ - **Boundary and result.** Name the lower-trust principal, the input or action, the control that should stop it, the boundary that it crosses, and the concrete result. A missing best practice, a guess about the deployment, a generic parser crash, or an effect on the caller only is not a finding.
33
+ - **Source visibility.** A proxy, an identity policy, a provider setting, or a header can stop an attack. When the repository does not show it, do not assume that it exists or that it is missing. Mark the finding `needs_validation`, with the missing fact and a safe way for the owner to check it.
34
+ - **Status.** `confirmed` means that the source and a bounded check show the whole path and the result. `needs_validation` means that one named fact blocks the proof. Only `confirmed` has a severity.
35
+ - **Severity.** Calibrate with these anchors, and never go above the demonstrated impact:
36
+ - `critical`: an unauthenticated actor gets code execution, full data-store access, or takeover of any account.
37
+ - `high`: an actor fully defeats an explicit control with real consequences, such as an authentication bypass, a read or write across tenants, or stored script that runs for other users.
38
+ - `medium`: a real violation with a small blast radius or uncommon preconditions.
39
+ - `low`: disclosure of non-secret internals, or an effect that needs long effort for little gain.
40
+ - `informational`: a confirmed observation with minimal impact, useful as a step in a larger finding.
41
+ - **Fix.** Name the invariant that the code must enforce, and the narrowest change that enforces it at the last trusted decision point. Add a regression test idea. Do not edit the target source.
42
+
43
+ ## Full audit
44
+
45
+ The target is the whole codebase of the current branch, or the path that the user gives. Work alone, in this order, and do not skip a step.
46
+
47
+ 1. **Map.** Read the repository: its entry points, trust boundaries, authentication, data stores, build and release files, and dependencies. Run `git rev-parse HEAD` and `git status --short`, and note whether the worktree is dirty. List the components in scope, and state what is out of scope.
48
+ 2. **Choose references.** For each topic in the table below that the map shows, read the reference now.
49
+ 3. **Hunt.** For each component and each attack class that applies, trace untrusted input to the dangerous sink, and check that each control checks the right permission on the right resource. Write each candidate as a boundary hypothesis. Drop a candidate that fails the rules above.
50
+ 4. **Validate.** Re-read the source of each candidate, as if you did not write it. Search for a control that stops it. Run a bounded check when the sandbox allows. Set the status, and the severity for `confirmed`.
51
+ 5. **Report.** Write `.tmp/security-audit/REPORT.md` at the repository root. First run `git check-ignore -q .tmp/`: if Git does not ignore `.tmp`, stop and tell the user. Do not edit `.gitignore`.
52
+
53
+ The report has these sections:
54
+
55
+ - **Scope and coverage:** the commit, the dirty state, the path, the components that you read, and the attack classes that you checked. State that the audit is one pass, and that a run on a path is partial.
56
+ - **Findings:** the `confirmed` findings, sorted by severity. Give each one a title, the `file:line`, the severity, the boundary (principal, input, control, crossing, result), the evidence, and the fix.
57
+ - **Needs validation:** each blocked finding with the missing fact and the safe check.
58
+ - **Rejected:** the candidates that you dropped, with the reason, so that the next run does not repeat them.
59
+
60
+ Tell the user the path of the report and the count of findings for each severity.
61
+
62
+ ## References
63
+
64
+ Each file lists attack classes for one kind of target. Read a file only when the map shows its topic.
65
+
66
+ | Read | When the target has |
67
+ | ---- | ------------------- |
68
+ | [`ATTACK-CLASSES.md`](references/ATTACK-CLASSES.md) | Any target. Read it in step 2. |
69
+ | [`WEB-PROTOCOL-AND-AUTH.md`](references/WEB-PROTOCOL-AND-AUTH.md) | HTTP servers, proxies, sessions, CSRF, JWT, OAuth, SAML, MFA, passkeys, API keys, or mTLS. |
70
+ | [`CLIENT-SIDE.md`](references/CLIENT-SIDE.md) | A single-page app, a browser extension, a webview, a service worker, CORS, WebSockets, or DOM rendering. |
71
+ | [`AI-AND-LLM.md`](references/AI-AND-LLM.md) | Prompts, retrieval, agent memory, tool calls, or an MCP server or client. |
72
+ | [`MEMORY-SAFETY-AND-BINARY.md`](references/MEMORY-SAFETY-AND-BINARY.md) | C, C++, or unsafe Rust, parsers, FFI, loaders, or kernel code. |
73
+ | [`SUPPLY-CHAIN-AND-RELEASE.md`](references/SUPPLY-CHAIN-AND-RELEASE.md) | Dependency resolution, CI, signing, release, updates, or plugins. |
74
+ | [`CLOUD-AND-DEPLOYMENT.md`](references/CLOUD-AND-DEPLOYMENT.md) | IAM, infrastructure as code, containers, Kubernetes, serverless, or ingress. |
75
+ | [`PROTOCOLS-RPC-AND-MESSAGING.md`](references/PROTOCOLS-RPC-AND-MESSAGING.md) | gRPC, GraphQL, custom protocols, queues, brokers, or webhooks. |
76
+ | [`RESOURCE-EXHAUSTION-AND-AVAILABILITY.md`](references/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md) | Untrusted work that uses shared CPU, memory, disk, workers, quotas, or spend. |
77
+ | [`DATA-ISOLATION-AND-LIFECYCLE.md`](references/DATA-ISOLATION-AND-LIFECYCLE.md) | Multiple tenants, caches, search, exports, backups, migrations, or deletion. |
78
+ | [`DESKTOP-MOBILE-AND-LOCAL-IPC.md`](references/DESKTOP-MOBILE-AND-LOCAL-IPC.md) | Native apps, deep links, webview bridges, local daemons, or sockets. |
79
+
80
+ ## Mistakes to avoid
81
+
82
+ 1. A checklist deviation that you report as a vulnerability.
83
+ 2. Defense-in-depth advice with no reachable violation.
84
+ 3. A test against a live or shared environment when a local check is not enough.
85
+ 4. A guess about provider, proxy, browser, or deployment behavior that the source does not show.
86
+ 5. Intended authority of the same principal, or an effect on the caller only, that you report as a crossing.
87
+ 6. An effect that you report as stronger than the effect that you observed.
@@ -0,0 +1,8 @@
1
+ {
2
+ "repository": "https://github.com/cloudflare/security-audit-skill",
3
+ "path": "skills/security-audit",
4
+ "commit": "c1c8a8c1471069fb0e188eeaff69b8e8db6564a8",
5
+ "license": "MIT",
6
+ "modified": true,
7
+ "notes": "Rewrote SKILL.md under rules/writing.md and renamed the skill with the dot- prefix. Kept guidance mode and the severity anchors, and reduced the full audit to a single-agent pass in 5 steps (map, choose references, hunt, validate, report) that writes one REPORT.md. Dropped the six-phase workflow with subagents, the run directory and write isolation, the promotion procedure, the run profiles and the cost budget, the prior-run ledger, report-schema.json, the Node validators and their tests, and the diff-scoped run. Dropped RECONNAISSANCE.md, HUNTING.md, and VALIDATION-AND-REPORTING.md, which only serve those phases. Moved ATTACK-CLASSES.md and the 10 domain companion files to references/ with their upstream names. In the references, replaced the em dashes and arrows, removed the subagent_type labels, and changed \"Phase 1\" to \"the map step\"."
8
+ }
@@ -0,0 +1,83 @@
1
+ # AI, LLM, and Agent Hunting
2
+
3
+ #### When to use this file
4
+
5
+ Reach for this file when a language model participates in a trust-sensitive decision: chatbots and assistants, RAG pipelines, persistent agent memory, agent/tool-calling loops, MCP servers and clients, code that builds prompts from untrusted input, or code that consumes model output and acts on it. The important data flow is *untrusted content, then a model or memory, then a capability, authority, or sink*.
6
+
7
+ Use this alongside `ATTACK-CLASSES.md`, not instead of it. Transport, access control, query construction, filesystem use, and output rendering remain ordinary trust boundaries. This file covers the model-specific delegation layer. Split large targets by retrieval, memory, tool dispatch, MCP, and output handling.
8
+
9
+ ## Core discipline (include in every agent prompt for this domain)
10
+
11
+ ```
12
+ - Prompt injection alone is not a finding. Require a code-level boundary failure: content reaches another principal's context, invokes authority the requester lacks, discloses data they cannot read, or drives a sink they cannot reach directly.
13
+ - Model output, memory, tool descriptions, and MCP responses are untrusted inputs. Point to the code that grants authority, trusts output, writes durable state, or feeds a sink.
14
+ - A guardrail prompt is not a security boundary. Count only deterministic checks, resource-scoped authorization, isolation, binding, and constrained credentials.
15
+ - State the attacker, affected principal, effective execution identity, resource, exact action, authority used, and observable impact. An intentional direct request to use the requester's existing authority is not a delegation defect merely because a model executes it.
16
+ - Authorization and action binding are separate controls. Attacker-controlled content that causes an action under an affected principal's valid authority is an action-binding failure when that principal did not intentionally request or approve the exact action.
17
+ - Classify every candidate as `confirmed` only after source evidence and bounded local validation establish the boundary and result. Use `needs_validation` when a required provider, deployment, model, renderer, or identity behavior is not observable locally.
18
+ ```
19
+
20
+ ## Context, retrieval, and memory attack classes
21
+
22
+ **Indirect injection through retrieved or ingested content**
23
+ An attacker can write a RAG document, indexed page, file, email, issue body, tool response, or metadata that enters a different principal's model context. Trace who can write each source, how retrieval scopes it, whose session consumes it, and what capability is enabled there. Check isolation, resource authorization, and binding to the consuming principal's intent separately. The defect is a missing deterministic control, not persuasive text by itself.
24
+
25
+ **Cross-session or cross-tenant context bleed**
26
+ Conversation history, embeddings, retrieval results, or prompt caches are keyed too broadly. Verify tenant and ACL filters in the query itself and every cache key. A tenant field stored on an object is not enforcement if an alternate query, shared cache, or batch path omits it.
27
+
28
+ **Persistent memory poisoning**
29
+ Attacker-controlled content or model summaries are written into memory that later shapes another task, user, or privileged session. Review who may create, update, merge, and delete memory; its provenance and tenant scope; whether low-trust observations become durable instructions or facts; and whether retrieval distinguishes user preferences from tool policy. Memory intentionally saved by a user and used only for that user's intentional, allowed requests is not a cross-boundary finding.
30
+
31
+ **Prompt role and provenance confusion**
32
+ Prompt assembly lets untrusted text impersonate a system message, prior turn, tool result, policy, or memory record. Look for string concatenation, untyped history, caller-controlled role fields, and serialization round trips that lose source labels. Confirm that the forged provenance changes a deterministic trust decision or reaches a meaningful capability.
33
+
34
+ ## Tool and action attack classes
35
+
36
+ **Tool-argument injection into a downstream sink**
37
+ Model-produced arguments reach SQL, shell, file, URL-fetch, or privileged APIs without handler-side validation. Treat the tool schema as input parsing, then follow each field from decoded call to sink. Structured output narrows shape; it does not establish authorization, safe paths, safe URLs, or query semantics.
38
+
39
+ **Excessive agency and confused-deputy authority**
40
+ The agent uses a service identity or broad credential, while the tool handler does not re-check the requesting principal's permission on the named resource. Verify both the effective identity and whether the caller could perform that exact operation through the normal product interface. A shared credential with enforced per-user query scope is not a defect.
41
+
42
+ **Action-confirmation and approval binding**
43
+ A user approves one described action but execution can use changed arguments, a different resource, a different principal, or a later model turn. An action-binding defect also exists when attacker-controlled content causes a side effect under a victim's valid authority without the victim's intentional request or approval, even if generic authorization permits the victim to perform it. Review whether intent or confirmation binds the normalized tool name, complete argument object, requester, target, amount, expiry, and batch membership. Check retries and resumed sessions: an approval must not authorize a mutated or duplicate side effect.
44
+
45
+ **Tool-schema and dispatcher disagreement**
46
+ The schema accepts aliases, extra fields, duplicate keys, coercions, nested free-form objects, or out-of-range values that the dispatcher or handler interprets differently. Compare schema validation, canonicalization, generated bindings, and handler defaults. Validate again where values become resource selectors or security-relevant options.
47
+
48
+ **Unbounded delegated action loops**
49
+ A bounded request can enqueue repeated spend, send, mutation, or external API work without a per-request budget, per-action authorization, cancellation, or idempotency control. Confirm impact on shared cost, quotas, other users, or durable state. Do not test by exhausting a service; use code-level accounting and a locally bounded loop.
50
+
51
+ ## MCP and sub-agent trust classes
52
+
53
+ **Sub-agent and MCP trust inheritance**
54
+ A delegated task receives the full session, credentials, memory, or capabilities rather than the least authority required. Check the principal and tenant carried into each call, capability narrowing, credential audience, and whether delegated results are treated as untrusted on return.
55
+
56
+ **MCP server and tool identity confusion**
57
+ Calls or results are routed by attacker-influenceable server names, tool names, request IDs, resource URIs, or model-selected aliases rather than the authenticated connection and outstanding request. Check whether two servers can claim the same tool or resource identity, whether reconnect changes the binding, and whether a response from one server can satisfy another server's pending call.
58
+
59
+ **MCP metadata and schema as policy**
60
+ Tool descriptions, resource metadata, prompts, completion hints, or schemas supplied by an MCP peer are trusted as policy or authorization. These fields can guide the model but cannot grant capability. Find the deterministic allowlist, server identity check, and handler authorization that remain authoritative when metadata conflicts.
61
+
62
+ ## Output and disclosure attack classes
63
+
64
+ **Insecure output rendering**
65
+ Model output reaches an executing HTML, Markdown, template, URL, or command sink without the sink's required encoding and policy. For browser rendering, verify auto-loaded resources and CSP or sanitization in `CLIENT-SIDE.md`; renderer behavior outside the repository makes the candidate `needs_validation`.
66
+
67
+ **Sensitive context extraction**
68
+ The assembled context contains credentials, another user's data, private source, or policy values that themselves grant access, and user-influenced output exposes them. Read prompt assembly and data-fetch code. Disclosure of generic instructions or behavior that does not cross a data boundary is not a finding.
69
+
70
+ ## Universal moves (apply across the above)
71
+
72
+ - Draw four maps first: each execution identity, each capability, every writable context or memory source, and each output destination. Then connect the principal at the start to the authority at the end.
73
+ - Start at side-effecting tools and work backward through dispatcher, schema, confirmation, model context, retrieval, and ingestion. Start at durable memory reads and trace every writer.
74
+ - Compare direct, queued, retry, resume, batch, and delegated paths for the same action. The strongest gate must apply after arguments are final and before every side effect.
75
+
76
+ ## Validation rules (apply before reporting ANY finding here)
77
+
78
+ 1. Name the crossed boundary and observable result: attacker, affected principal or shared resource, execution identity, target, and unauthorized or unrequested action or disclosure.
79
+ 2. For confused-deputy authority claims, prove the tool lacks requester-and-resource authorization and that the attacker cannot perform the same action normally. For action-binding claims, instead prove attacker-controlled content caused an action under the affected principal's authority that the principal did not intentionally request or approve. Valid generic authorization does not establish that intent.
80
+ 3. For memory or retrieval claims, cite both the attacker-controlled write and the later cross-principal read or privileged decision. A shared record without a reachable consumer is not enough.
81
+ 4. For action binding, establish the intentional request or normalized approved object, if any, and compare it with the object the handler uses. Confirm a locally observable unrequested action, mutation, duplicate, or authority change without extending the test into harmful execution. For schema disagreement, compare the normalized validated object with the handler's object.
82
+ 5. For MCP identity claims, verify the authenticated connection, request correlation, tool namespace, and effective credential. Mark `needs_validation` if external server identity or deployment routing is required.
83
+ 6. Return `confirmed` findings only with a complete source trace and meaningful result. Return `needs_validation` for a specific unresolved boundary fact and state the bounded local or owner-observed check needed to resolve it.
@@ -0,0 +1,130 @@
1
+ # Attack Classes
2
+
3
+ #### Attack classes: choose and split based on the map step
4
+
5
+ Select attack classes relevant to the application type. Not every class applies to every codebase. The list below is a starting point; add application-specific classes from the map step and split large codebases per subsystem. Frame work as finding, validating, fixing, and prioritizing vulnerabilities. Keep validation to source review and bounded local fixtures; do not develop payload chains, test availability on live services, or take action in shared environments.
6
+
7
+ Use `confirmed` only when source evidence and bounded validation establish the full boundary and meaningful result. Use `needs_validation` when a specific deployment, provider, platform, identity, or runtime fact is unavailable; state the missing fact and the safe owner-observed or local check that resolves it.
8
+
9
+ > **Native / binary / kernel targets** (C/C++/Rust-unsafe, kernel modules, parsers and decoders, FFI, concurrent runtimes, binary loaders, JITs, firmware): use the memory-safety, integer/ABI, concurrency, binary-loader, and privileged-interface classes in [MEMORY-SAFETY-AND-BINARY.md](MEMORY-SAFETY-AND-BINARY.md).
10
+ >
11
+ > **AI / LLM / agent targets** (chatbots, RAG, persistent memory, tool-calling agents, MCP servers/clients, prompt assembly, or model-controlled actions): use the context, memory-poisoning, action-binding, tool-schema, MCP-identity, and output classes in [AI-AND-LLM.md](AI-AND-LLM.md).
12
+ >
13
+ > **HTTP, web, and identity targets** (ordinary web apps, APIs, reverse proxies, CDNs, gateways, custom HTTP parsers, sessions, CSRF, JWT, OAuth/OIDC, SAML, MFA, passkeys, account recovery/linking, API keys, or mTLS): use [WEB-PROTOCOL-AND-AUTH.md](WEB-PROTOCOL-AND-AUTH.md).
14
+ >
15
+ > **Client-side and browser targets** (SPAs, browser extensions, embedded webviews, service workers, browser storage, cross-window messaging, CORS, WebSockets, or DOM rendering): use [CLIENT-SIDE.md](CLIENT-SIDE.md).
16
+ >
17
+ > **Supply-chain and release targets** (dependency resolution, generated inputs, CI, release/signing/promotion, updates, plugins, or extensions): use [SUPPLY-CHAIN-AND-RELEASE.md](SUPPLY-CHAIN-AND-RELEASE.md).
18
+ >
19
+ > **Cloud and deployment targets** (IAM, infrastructure as code, containers/Kubernetes, service mesh, serverless/edge, ingress, provider events, or runtime configuration): use [CLOUD-AND-DEPLOYMENT.md](CLOUD-AND-DEPLOYMENT.md).
20
+ >
21
+ > **Protocol, RPC, and messaging targets** (gRPC, GraphQL transports, Protobuf/Cap'n Proto/Thrift, custom protocols, queues, brokers, pub/sub, webhooks, or streaming RPC): use [PROTOCOLS-RPC-AND-MESSAGING.md](PROTOCOLS-RPC-AND-MESSAGING.md).
22
+ >
23
+ > **Resource-exhaustion and availability targets** (untrusted work can consume shared CPU, memory, disk, connections, workers, queues, quotas, or operator-owned spend): use [RESOURCE-EXHAUSTION-AND-AVAILABILITY.md](RESOURCE-EXHAUSTION-AND-AVAILABILITY.md).
24
+ >
25
+ > **Data-isolation and lifecycle targets** (multi-tenant stores, caches/search, object links, analytics, export/backup, migration, deletion, retention, or restore): use [DATA-ISOLATION-AND-LIFECYCLE.md](DATA-ISOLATION-AND-LIFECYCLE.md).
26
+ >
27
+ > **Desktop, mobile, and local-IPC targets** (native apps, deep links, webview bridges, exported components, privileged helpers, local daemons, Unix sockets/XPC/Binder/D-Bus): use [DESKTOP-MOBILE-AND-LOCAL-IPC.md](DESKTOP-MOBILE-AND-LOCAL-IPC.md).
28
+
29
+ **Injection**
30
+ Trace untrusted input from entry point to dangerous sink. What counts as a "dangerous sink" depends on the application:
31
+ - Web apps: SQL queries, HTML output, shell commands, template engines, file paths, HTTP redirects, deserialization
32
+ - Libraries: any function that processes caller-supplied data without validation, buffer operations, parsers, format strings
33
+ - CLI tools: shell command construction, file path handling, environment variable interpolation
34
+ - Services: query construction, message serialization, log injection, LDAP/XPATH queries
35
+ - Client-side (browser/JS): DOM XSS, prototype pollution, `postMessage`/origin trust, and other browser-side classes, covered by the [CLIENT-SIDE.md](CLIENT-SIDE.md) companion blocks when selected
36
+
37
+ Do not stop at the obvious direct paths. Look for indirect injection: data stored safely, then retrieved and used in a dangerous context by different code. Look for injection through field names, keys, headers, and metadata, not just values. Look for injection into secondary systems (logs, caches, search indexes, analytics).
38
+
39
+ **Access control**
40
+ Verify that a caller cannot do something outside its authority. Go beyond checking whether permission checks exist, verify they check the *right* permission for the *right* resource via the *right* mechanism:
41
+ - Is there a path to the same state change that checks a different (weaker) permission?
42
+ - Can a field in the request body override what the permission system intended to restrict?
43
+ - Are there endpoints that gate on authentication but forget authorization?
44
+ - Does the same resource have multiple access paths with inconsistent checks?
45
+ - What about bulk/batch/export/import operations: do they enforce per-item permissions?
46
+
47
+ For complex access models, split into separate agents for auth bypass vs authorization logic.
48
+
49
+ **Resource and file handling**
50
+ - Path traversal (reading/writing outside intended directories), including through symlinks, encoded sequences, and null bytes
51
+ - SSRF (making the application fetch attacker-controlled URLs), including through redirects, DNS rebinding, and URL parser differentials
52
+ - Unsafe deserialization, archive extraction (zip slip), temp file handling
53
+ - Memory safety (if applicable): buffer overflows, use-after-free, integer overflow
54
+ - Race conditions on file operations (TOCTOU between check and use)
55
+
56
+ **Cryptography and secrets**
57
+ - Weak randomness for security-critical values (tokens, keys, nonces)
58
+ - Hardcoded secrets, secrets in logs, error messages, URLs, or client-visible responses
59
+ - Broken key derivation, missing HMAC verification, nonce reuse
60
+ - Timing side-channels on secret comparison
61
+ - Misuse of crypto primitives (ECB mode, unauthenticated encryption, static IVs, etc.)
62
+ - What happens when crypto operations fail? Does the error path fall back to no-crypto?
63
+
64
+ **Business logic**
65
+ Hunt logic errors by hand: standard scanners cannot find them, and they yield high-impact findings. For each major workflow:
66
+ - **State machine violations**: Can you skip steps? Go backwards? Reach an invalid state? What happens if you replay a completed flow? What about partial failure: if step 2 of 3 fails, is step 1 rolled back?
67
+ - **Race conditions with business impact**: Concurrent operations that produce invalid states (double-spend, double-approve, lost updates). Focus on operations that check-then-act non-atomically.
68
+ - **Numeric/quantity manipulation**: Negative values, zero values, overflow, precision loss, type coercion between string and number.
69
+ - **Access boundary violations**: Not "does the permission check exist" but "is it the right check for the business rule?" Can input to one operation bypass a restriction enforced on a different operation for the same effect?
70
+ - **Implicit trust assumptions**: Data from storage, config, other components, or plugins assumed safe because "we validated it on the way in." What if a different code path wrote it?
71
+ - **Time-based logic**: Expiry checks, scheduling, rate windows, clock skew. What happens at exact boundary moments? What about timezone differences between components?
72
+ - **Default and fallback behavior**: What is the security posture when config is missing? When a feature flag is off? When a dependency is unavailable? When the system is mid-migration?
73
+
74
+ **Feature abuse and data leakage**
75
+ Legitimate features used for unintended purposes. Look for bugs in the design, not only in the code:
76
+ - **Export/backup as exfiltration**: Can a low-privilege user trigger an export, snapshot, or backup that includes data above their access level? Can they export other users' data? Does the export include deleted/draft/private content? Revision history that was supposed to be pruned?
77
+ - **Import/restore as injection**: Can import overwrite existing data? Can it create records that bypass normal validation? Can it inject content into collections the user has no write access to? Does it respect the same permission model as the UI?
78
+ - **Search/filter/sort as oracle**: Can search queries reveal whether content exists that the user cannot directly access? Do filter parameters let users probe statuses, roles, or fields they should not know about? Does sorting by a hidden field reveal its values through result ordering?
79
+ - **Enumeration through side effects**: Do error messages differ between "does not exist" and "no access"? Do response times differ? Response sizes? HTTP status codes? Can you enumerate users through password reset, invite, or registration flows?
80
+ - **Preview/draft/staging leakage**: Are preview tokens scoped to one item or do they unlock broader access? Can draft content be discovered through search, RSS feeds, sitemaps, or API listing endpoints? Can cache headers cause a CDN to serve private content publicly?
81
+ - **Notification/webhook as SSRF**: Can a user set a notification URL, webhook URL, or callback URL that the server fetches? Is it validated against internal networks? What about after a redirect?
82
+
83
+ **Chained vulnerabilities and trust boundaries**
84
+ Individually allowed or contained behavior can become a vulnerability when another component or lifecycle step relies on a stronger guarantee:
85
+ - **Multi-step boundary failures**: Map what a low-privilege principal may read, write, invoke, and retain, then connect only concrete outputs to later trust decisions. Confirm each prerequisite and do not assume a downstream effect.
86
+ - **Cross-component trust gaps**: Component A validates input and passes it to component B. Compare the exact guarantee A produces with what B assumes, including truncation, type coercion, normalization, tenant scope, and plugin/extension access.
87
+ - **Second-order use**: Data safe when stored may become dangerous in a later context. A field name becomes a JSON path, a slug becomes a file path, escaped text enters raw rendering, or a stored string becomes a URL, regex, template, or policy expression.
88
+ - **Scope and capability growth**: Token, API-key, plugin, OAuth, MCP, or AI capabilities become broader after delegation, refresh, caching, role change, or composition. Name the concrete operation the resulting principal should not have.
89
+ - **Timing and ordering**: Review setup, migration, soft-delete, revoke/cache expiry, check/use, and validate/consume windows. Confirm stale state is accepted before reporting.
90
+ - **Rollback and recovery**: Undelete, restore, revision rollback, and cancellation must apply current ownership, validation, and authorization. Confirm which invalid state is restored.
91
+
92
+ **Wildcard**
93
+ You are not given a category. Find vulnerabilities outside the standard classes already assigned.
94
+
95
+ Read code that looks boring or disconnected from security. Follow incomplete, experimental, compatibility, and fallback features, but retain the same concrete boundary and validation requirements as every other class.
96
+
97
+ Use these starting points, but do not limit yourself to them:
98
+ - What is the strangest code in the codebase? Why does it exist? What happens if it is abused?
99
+ - Are there any features that feel half-finished, experimental, or bolted on? Those have the weakest security because they got the least review.
100
+ - What happens if you use the API in a way the frontend never would? The UI constrains users, but the API does not. What API calls are possible but never made by the client?
101
+ - Are there any hidden or undocumented endpoints, parameters, headers, or features? Look at route registrations, middleware, and config for things that are not in the docs.
102
+ - What happens when you mix features that were not designed to work together? Localization + preview + caching. Import + plugins + webhooks. OAuth + impersonation + API keys.
103
+ - Is there anything interesting in the git history? Reverted security fixes, commented-out auth checks, secrets that were committed then removed (still in history).
104
+ - Which valid-account actions affect other users, shared integrity, availability, or operator-owned cost? Verify containment, quotas, authorization, and recovery around those actions.
105
+ - Which operations are irreversible or require elevated confirmation? Bind authorization and approval to the final principal, action, and resource.
106
+ - What assumptions does the code make about the environment? That the database is local, that the clock is accurate, that DNS is trustworthy, that the filesystem is case-sensitive?
107
+ - Look at the test files: what are they **not** testing? Compare the edge cases the developer thought about (tests exist) with the ones they did not (no tests).
108
+
109
+ Pursue anomalies inside your assigned scope until the invariant is settled. If something looks strange, read it until you can state whether it is safe. If a function has a comment explaining why it is safe, verify the explanation. If a variable is named `temp` or `hack` or `legacy`, read it closely.
110
+
111
+ **Obvious things**
112
+ Other agents hunt subtle bugs. This agent checks the basic exposures that are easy to overlook because everyone assumes someone else already checked them:
113
+ - Are there any hardcoded passwords, API keys, tokens, or secrets in the source? (grep for `password`, `secret`, `apikey`, `token`, `Bearer`, `-----BEGIN`, common default passwords)
114
+ - Are there any TODO/FIXME/HACK/XXX comments that reference security? (`TODO: add auth`, `FIXME: validate input`, `HACK: skip permission check`)
115
+ - Is debug mode / dev mode properly gated? Can it be enabled in production via environment variable, query parameter, or header?
116
+ - Are there test/example/seed credentials that work in production?
117
+ - Is there a `/debug`, `/admin`, `/test`, `/status`, `/health`, `/metrics`, `/env`, `/.env`, `/config` endpoint that is unprotected?
118
+ - Are there any `.env`, `.env.local`, `credentials.json`, `*.pem`, `*.key` files checked into the repo?
119
+ - Does the `.gitignore` actually cover secrets, uploads, and local config?
120
+ - Are dependencies pinned? Are there known CVEs in the dependency tree? (check lockfiles)
121
+ - Are there any `eval()`, `exec()`, `child_process`, `Function()`, `vm.runInContext`, `import()` with dynamic input?
122
+ - Are CORS headers set to `*` or overly permissive? Is `Access-Control-Allow-Credentials` combined with a wildcard origin?
123
+ - Are cookies missing `HttpOnly`, `Secure`, or `SameSite` attributes?
124
+ - Are there any open redirects? (parameters named `redirect`, `return`, `next`, `url`, `goto`, `continue` that feed into redirects without validation)
125
+ - Is TLS enforced? Are there any HTTP-only endpoints?
126
+ - Are error responses in production returning stack traces, internal paths, or SQL errors?
127
+
128
+ This agent does not need to be creative. It needs to be thorough and literal. Check every item. Report each result.
129
+
130
+ **Important**: For any finding this agent reports, it must verify the full code path, not just surface appearance. If a cookie is missing `HttpOnly`, check whether the cookie contains security-sensitive data and whether JS needs to read it by design. If an error message contains a field name, check whether the field is ever actually populated with sensitive data. A flag is not a finding. Trace the impact before reporting.
@@ -0,0 +1,83 @@
1
+ # Client-Side and Browser Hunting
2
+
3
+ #### When to use this file
4
+
5
+ Reach for this file when meaningful trust decisions or untrusted rendering happen in a browser: single-page apps, browser extensions, embedded webviews, service workers, offline applications, and code that renders attacker-influenceable content into the DOM, receives cross-window messages, or uses browser storage. These paths include sources the server never sees, such as URL fragments, `window.name`, `postMessage`, and previously cached content.
6
+
7
+ Use alongside `ATTACK-CLASSES.md`. This file covers browser sources and sinks, origin boundaries, browser persistence, and cross-site state oracles. Use `DESKTOP-MOBILE-AND-LOCAL-IPC.md` for the native side of a webview bridge, and `WEB-PROTOCOL-AND-AUTH.md` for server-side CSRF, sessions, and auth callbacks.
8
+
9
+ ## Core discipline (include in every agent prompt for this domain)
10
+
11
+ ```
12
+ - A client-side candidate needs a controllable source and an executing or disclosing sink. Name both and show attacker-influenced data reaching the sink.
13
+ - The impact must reach a victim's session, another origin, or shared persistence. Self-injection and disclosure of the attacker's own data are not findings.
14
+ - Framework escaping, browser same-origin policy, CSP, COOP/CORP, service-worker scope, and modern noopener defaults are real controls. Verify them before assigning impact.
15
+ - Browser storage and caches are shared by origin and may outlive login state. Identify who writes, who reads, and which account, tenant, or worker lifecycle clears each record.
16
+ - Use `confirmed` only for complete source evidence plus bounded local browser tests. Use `needs_validation` when renderer, extension permission, deployed header, or browser-policy behavior is required but unavailable.
17
+ ```
18
+
19
+ ## DOM and object-state attack classes
20
+
21
+ **DOM-based XSS**
22
+ Trace `location` fields, `document.referrer`, `window.name`, message data, storage, and browser-controlled document state into `innerHTML`, `outerHTML`, `document.write`, string-evaluating APIs, executable URLs, jQuery HTML APIs, or framework escape hatches. Interpolation escaped by the framework is not a finding.
23
+
24
+ **DOM clobbering**
25
+ Attacker-injected `id` or `name` attributes shadow a global, form property, configuration object, or initialization flag later trusted by code. Require both a markup path that preserves the attribute and a security-relevant use of the clobbered value.
26
+
27
+ **Prototype pollution and gadget chain**
28
+ An attacker-controlled key reaches a recursive write such as deep merge or path assignment and modifies prototype state. Then a reachable gadget consumes the polluted property to change authorization, execution, navigation, or rendering. `JSON.parse`, a shallow copy, or pollution without a gadget is not enough.
29
+
30
+ ## Cross-origin messaging and network attack classes
31
+
32
+ **`postMessage` origin and source trust**
33
+ A handler performs a sensitive action with `event.data` without an exact origin allowlist and, where multiple frames share an origin, the expected `event.source`. On the send side, sensitive data sent to `*` reaches an unintended embedder. Weak substring, prefix, suffix, or unanchored-regex origin matching is not an origin check.
34
+
35
+ **Cross-site WebSocket request use**
36
+ A WebSocket upgrade accepts ambient cookies from an untrusted origin without an `Origin` check or channel-specific token, allowing the victim's session to read or mutate data. Confirm both the upgrade behavior and a security-relevant message handler.
37
+
38
+ **Credentialed CORS trust**
39
+ The server reflects or weakly matches `Origin` while allowing credentials and returns sensitive responses. A bare wildcard with credentials is rejected by browsers; report only the actual reflected/allowed origin path and cross-origin data or mutation.
40
+
41
+ ## Service-worker and browser-storage attack classes
42
+
43
+ **Service-worker registration and scope takeover**
44
+ Attacker-influenceable content can become the registered worker script, control a path that receives an over-broad `Service-Worker-Allowed` scope, or alter update imports without integrity control. Verify the final script URL, response MIME type, origin, scope, and who controls every imported script. A normal same-origin worker with intended scope is not a defect.
45
+
46
+ **Service-worker cache and identity confusion**
47
+ The worker caches personalized responses without including account, tenant, authorization state, or request mode in its policy, then serves them after account switch or logout. Review fetch-event routing, cache names and keys, navigation fallbacks, cache cleanup, and whether error/offline paths return another user's prior response.
48
+
49
+ **Browser-storage disclosure and stale authorization**
50
+ Tokens, private responses, draft data, or authorization decisions remain in `localStorage`, `sessionStorage`, IndexedDB, Cache Storage, extension storage, or client state and become readable by another account or less-trusted same-origin component. Storage of a token alone is not a finding; require a realistic reader with less authority, or continued use after revocation/logout.
51
+
52
+ **Cross-context storage and broadcast confusion**
53
+ `storage` events, `BroadcastChannel`, shared workers, or origin-wide caches carry identity or commands between tabs without binding them to the current session. Check account switching, private/public windows, tenant changes, and stale tabs that can overwrite newer auth state.
54
+
55
+ ## Cross-site information leak classes
56
+
57
+ **XS-Leaks and cross-origin state oracles**
58
+ An attacker page can distinguish protected cross-origin state through resource load/error events, frame or window state, redirect behavior, timing, cache state, or response size while the browser attaches victim credentials. Require one concrete secret-bearing predicate such as whether a private object, role, or account exists. Generic timing variance or public-resource availability is not a finding.
59
+
60
+ **Window and opener state disclosure**
61
+ A cross-origin window's permitted metadata or navigation result reveals protected state, or a retained opener/named-window relationship lets an attacker-controlled page influence a privileged navigation. Check COOP, frame protections, `noopener`, exact origin, and whether the observable state is confidential.
62
+
63
+ ## UI-redress and navigation attack classes
64
+
65
+ **Clickjacking**
66
+ A framed, state-changing action lacks effective `frame-ancestors`, `X-Frame-Options`, or equivalent UI isolation. Require the sensitive action and confirm it can complete in the framed state; missing headers on read-only content are hardening notes.
67
+
68
+ **Client-side navigation confusion**
69
+ A client source controls redirect or navigation without scheme and destination policy, including executable `javascript:` or `data:` destinations. Reverse tabnabbing applies only where code explicitly keeps `window.opener`, uses `window.open` without isolation, or supports a browser without implicit `noopener`.
70
+
71
+ ## Universal moves (apply across the above)
72
+
73
+ - Start from DOM, navigation, worker, message, and storage sinks, then trace backward to browser-only and server-controlled sources. Record the browser policy that should stop the path.
74
+ - Test account switch, logout, worker update, offline fallback, and stale-tab state with a local test origin and dummy accounts. Do not use production users, origins, or shared services.
75
+ - For XS-Leaks, list only predicates proved by source and local browser behavior. Then identify the response headers or rendering choice that would remove the oracle.
76
+
77
+ ## Validation rules (apply before reporting ANY finding here)
78
+
79
+ 1. Cite the source, sink, browser policy, affected origin/session, and observable mutation or disclosure.
80
+ 2. For prototype pollution, prove the recursive write and a security-relevant gadget. For DOM clobbering, prove the markup survives and the shadowed value is used.
81
+ 3. For service workers and storage, prove lifecycle reachability: an attacker-controlled write or cache entry must reach a different account, tenant, or later authorization state.
82
+ 4. For messaging, CORS, WebSocket, and XS-Leaks, show exact origin/source validation and the protected state or action exposed. Confirm that CSP, COOP/CORP, cookies, and SameSite policy do not already block it.
83
+ 5. Return `confirmed` findings only with a complete client path and bounded local evidence. Return `needs_validation` with the precise deployed header, extension permission, browser version, or renderer behavior an owner must verify.