@lornatang/dsh-codex-security 0.1.7 → 0.1.8

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 (55) hide show
  1. package/CHANGELOG.md +118 -103
  2. package/README.md +196 -189
  3. package/README.zh.md +196 -189
  4. package/docs/ARCHITECTURE.md +59 -53
  5. package/docs/ARTIFACTS.md +49 -46
  6. package/docs/CODEX-COMPATIBILITY.md +17 -0
  7. package/docs/SPEC.md +43 -43
  8. package/docs/TOOLS.md +364 -341
  9. package/docs/VALIDATION.md +33 -31
  10. package/docs/superpowers/plans/2026-11-16-deep-scan.md +71 -0
  11. package/docs/superpowers/specs/2026-11-16-deep-scan-design.md +31 -0
  12. package/lib/constants.js +3 -3
  13. package/lib/contracts.js +114 -34
  14. package/lib/deep-coordinator.js +599 -0
  15. package/lib/deep-host.js +36 -0
  16. package/lib/deep-worker.js +254 -0
  17. package/lib/git.js +24 -22
  18. package/lib/index.js +23 -1
  19. package/lib/secure-read.js +229 -0
  20. package/lib/service.js +403 -62
  21. package/lib/state-lock.js +71 -0
  22. package/lib/store.js +33 -15
  23. package/lib/target.js +33 -13
  24. package/lib/tools.js +54 -19
  25. package/lib/types/constants.d.ts +1 -1
  26. package/lib/types/contracts.d.ts +5 -2
  27. package/lib/types/deep-coordinator.d.ts +70 -0
  28. package/lib/types/deep-host.d.ts +32 -0
  29. package/lib/types/deep-worker.d.ts +110 -0
  30. package/lib/types/git.d.ts +10 -10
  31. package/lib/types/index.d.ts +1 -1
  32. package/lib/types/secure-read.d.ts +15 -0
  33. package/lib/types/service.d.ts +20 -4
  34. package/lib/types/state-lock.d.ts +9 -0
  35. package/lib/types/store.d.ts +5 -2
  36. package/lib/types/target.d.ts +1 -0
  37. package/lib/types/tools.d.ts +3 -2
  38. package/lib/types/types.d.ts +42 -7
  39. package/lib/types/util.d.ts +4 -0
  40. package/lib/types/worker-preset.d.ts +18 -0
  41. package/lib/util.js +27 -4
  42. package/lib/worker-preset.js +8 -0
  43. package/package.json +131 -123
  44. package/schemas/coverage.schema.json +136 -134
  45. package/skills/README.md +122 -116
  46. package/skills/assess-patch-risk/SKILL.md +10 -0
  47. package/skills/attack-path-analysis/SKILL.md +10 -0
  48. package/skills/deep-security-scan/SKILL.md +15 -116
  49. package/skills/define-security-policy/SKILL.md +10 -0
  50. package/skills/finding-discovery/SKILL.md +10 -0
  51. package/skills/fix-finding/SKILL.md +14 -112
  52. package/skills/propose-security-hardening/SKILL.md +10 -0
  53. package/skills/track-findings/SKILL.md +12 -113
  54. package/skills/validation/SKILL.md +10 -0
  55. package/skills/verify-fix/SKILL.md +14 -108
package/README.md CHANGED
@@ -1,189 +1,196 @@
1
- ---
2
- description: "An artifact-backed security review layer for a dsh profile: 29 host tools, ten bundled skills, and a Web workbench that seal schema-validated scans, findings, coverage, and exports under the profile data directory."
3
- kind: "package-bundle"
4
- ---
5
-
6
- # @lornatang/dsh-codex-security
7
-
8
- English | [中文](README.zh.md)
9
-
10
- ## Summary
11
-
12
- `dsh-codex-security` adds a reproducible security review workflow to a dsh profile. It registers 29 `codex_security_*` host tools, ten bundled skills, and a Codex Security section in the Web GUI that lists scans, findings, coverage, and exports. The `add` command inserts one patch row into the profile and `remove` takes it out. The bundle records and validates what an agent reviews: it does not analyze source, execute target code, or dispatch workers, and each scan seals immutable artifacts under the profile data directory.
13
-
14
- ## Table of Contents
15
-
16
- - [Use this package](#use-this-package)
17
- - [Understand the implementation](#understand-the-implementation)
18
- - [Further Exploration](#further-exploration)
19
- - [Model Experience](#model-experience)
20
- - [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
21
- - [Dev Note](#dev-note)
22
-
23
- -----
24
-
25
- <a id="use-this-package"></a>
26
- ## Use this package
27
-
28
- The layer gives an agent a durable place to record a security review and gives the profile a Web panel to read and export the result: every scan binds its target, revision, and scope, keeps candidates and validations between turns, and seals a schema-checked artifact set on disk.
29
-
30
- ### Install into a profile
31
-
32
- ```text
33
- dsh plugin --profile <name> add @lornatang/dsh-codex-security
34
- dsh plugin --profile <name> remove @lornatang/dsh-codex-security
35
- ```
36
-
37
- For the GitHub 0.1.7 release, use `dsh plugin --profile <name> add https://github.com/Lornatang/dsh-codex-security/releases/download/v0.1.7/lornatang-dsh-codex-security-0.1.7.tgz`. The npm registry version may be older.
38
-
39
- The `add` command composes the layer into the profile: the profile's `cordis.patch.yml` gains an insert entry, row id `codex-security`, whose `config` starts from the bundle defaults `maxFiles: 5000`, `maxFileBytes: 1048576`, and `defaultMode: standard`; every other field takes its default from `src/config.ts`. The package manifest points `dsh.bundle.patch` at that document. The `remove` command deletes the row and leaves scans already written under the profile data directory untouched.
40
-
41
- Restart DSH after installing or removing, because the row is composed when the profile starts. On start the plugin logs `codex-security: registered 10 skills` and `codex-security: ready (state dir will resolve on first scan)`, and the Web GUI gains a Codex Security entry under Settings; profiles that do not run the Web client still receive the tools and skills.
42
-
43
- A new profile starts with no scans. The first request that touches the store — the workbench status request or `codex_security_inspect_setup` — resolves the state directory and creates `<stateDir>/repositories/`; a scan record appears only after one of the start tools runs, and the plugin itself reviews nothing.
44
-
45
- Scans live under `<stateDir>/repositories/<repoKey>/scans/<scanId>/`, where `repoKey` is the first 16 hexadecimal characters of the target root's SHA-256 and `scanId` is `cs_` plus 24 hexadecimal characters; `<stateDir>` defaults to `data/codex-security` next to the profile's `cordis.patch.yml` (for the shipped Web profile, `$DSH_HOME/profiles/web/data/codex-security`). `scan.json` holds the bound target, scope, inventory, progress, and diff list; `index.json` is a rebuildable list cache. Completion requires a draft submitted with `complete: true`, at least one coverage surface, a final disposition for every candidate and every bound diff file, and an unchanged snapshot digest; the plugin then validates the findings, coverage, and manifest documents against `schemas/`, records hashes in `scan-manifest.json`, and seals the scan. Sealed artifacts are immutable, triage is stored separately and stays editable, and exports default to `<stateDir>/exports/<scanId>.<format>`.
46
-
47
- Repeated default exports receive a numbered suffix; an explicitly supplied output path must not already exist.
48
-
49
- ### What you get
50
-
51
- The package owns three surfaces in the composed profile: 29 host tools, ten skills, and one workbench section in the Web GUI. [docs/TOOLS.md](docs/TOOLS.md) documents each tool's arguments and return shape.
52
-
53
- - **Setup and target inspection:** `codex_security_inspect_setup`, `codex_security_inspect_target`.
54
- - **Scan lifecycle:** `codex_security_start_scan`, `codex_security_start_standard_scan`, `codex_security_start_prompt_only_scan`, `codex_security_start_deep_scan`, `codex_security_get_scan_context`, `codex_security_update_scan_context`, `codex_security_update_scan_progress`.
55
- - **Discovery and candidates:** `codex_security_record_discovery_candidates`, `codex_security_list_candidates`.
56
- - **Validation:** `codex_security_record_candidate_validations`, `codex_security_record_candidate_attack_paths`.
57
- - **Draft and sealing:** `codex_security_record_scan_draft`, `codex_security_complete_scan`, `codex_security_fail_scan`, `codex_security_cancel_scan`.
58
- - **Agent artifacts:** `codex_security_save_artifact`, `codex_security_read_artifact`.
59
- - **Findings and triage:** `codex_security_list_findings`, `codex_security_set_finding_triage`, `codex_security_set_finding_remediation`.
60
- - **Diff review:** `codex_security_prepare_review_items`, `codex_security_list_review_items`, `codex_security_update_review_item`.
61
- - **Review and comparison:** `codex_security_list_scans`, `codex_security_get_scan`, `codex_security_compare_scans`.
62
- - **Export:** `codex_security_export_findings`.
63
-
64
- The skill catalog gains ten entries, each loaded from `skills/<name>/SKILL.md` at startup with `source: bundled` and both model and user invocation: `security-scan`, `security-diff-scan`, `deep-security-scan`, `fix-finding`, `verify-fix`, `triage-finding`, `threat-model`, `track-findings`, `resolve-dependency-alert`, and `vulnerability-writeup`; [skills/](skills/) holds the workflow text for each.
65
-
66
- The Web GUI gains one `settings.section` row, id `codex-security`, order 41, label Codex Security, registered by this package's client half (`src/client/index.tsx`, shipped as `lib/client.js`) through `@deepseek-ai/dsh-client-ui-slots` and `@deepseek-ai/dsh-client-ui-settings`. The panel shows the version, the resolved state directory, and scan and finding counts; it lists scans with status and age, and opens the selected scan's Overview, Findings, Coverage, and Artifacts & exports panels, including a triage selector and download links for SARIF, JSON, CSV, and Markdown. The panel reads the same service through HTTP routes under `/plugins/codex-security`.
67
-
68
- ### Configuration
69
-
70
- The bundle ships the row below, so a profile only lists what differs from it; the profile's own entry is applied after the layer and wins. The loader validates each field against `src/config.ts` and rejects an invalid value at startup instead of substituting a default.
71
-
72
- ```yaml
73
- # $DSH_HOME/profiles/web/cordis.patch.yml
74
- - id: codex-security
75
- config:
76
- maxFiles: 5000
77
- maxFileBytes: 1048576
78
- defaultMode: standard
79
- failOnSeverity: high
80
- allowExportOutsideWorkspace: false
81
- maxScanAgeDays: 30
82
- deepWorkers: 4
83
- deepMaxDiscoveryRuns: 40
84
- # stateDir: /var/lib/dsh/codex-security
85
- ```
86
-
87
- | Field | Default | Meaning |
88
- |---|---|---|
89
- | `stateDir` | empty | Directory that holds scans and exports. Empty resolves to `data/codex-security` next to the profile's `cordis.patch.yml`, or to `$DSH_HOME/profiles/web/data/codex-security` when no profile patch path is available. |
90
- | `maxFiles` | `5000` | Files inventoried per target, 1–200000; truncation is recorded as a scan warning. |
91
- | `maxFileBytes` | `1048576` | Per-file size cap for the reviewable inventory, 1024–67108864 bytes. |
92
- | `defaultMode` | `standard` | Mode used by `codex_security_start_scan`: `standard`, `prompt-only`, or `deep`. |
93
- | `failOnSeverity` | `high` | Policy gate threshold: `informational`, `low`, `medium`, `high`, `critical`, or `off`. |
94
- | `allowExportOutsideWorkspace` | `false` | Permits exports outside the state directory, the process working directory, and the target root. |
95
- | `maxScanAgeDays` | `30` | Age at which the workbench marks a scan as older than the policy window, 1–3650 days. |
96
- | `deepWorkers` | `4` | Worker budget recorded on deep scans, 1–32. |
97
- | `deepMaxDiscoveryRuns` | `40` | Discovery-pass budget recorded on deep scans, 1–10000. |
98
-
99
- -----
100
-
101
- <a id="understand-the-implementation"></a>
102
- ## Understand the implementation
103
-
104
- <details>
105
- <summary>Implementation internals — click to expand</summary>
106
-
107
- The layer is one patch row: an `insert` of id `codex-security`, package name `@lornatang/dsh-codex-security`, and three config values. Nothing is platform-gated on the host side; the manifest's `dsh.client.platform: web` scopes only the client bundle, while the host plugin registers tools and skills in any profile that injects them.
108
-
109
- Cordis must inject `tools` and `skills` before `apply` runs. `apply` builds a `SecurityService` from the resolved config and the profile patch path, then registers the 29 tools, discovers and registers the ten bundled skills from `skills/*/SKILL.md`, and binds optional HTTP routes, each in a disposal-aware effect. The state directory is not created at startup; `ScanStore.init` creates it on the first store access.
110
-
111
- A start tool resolves the target, binds revisions or diff facts, inventories reviewable files within the caps, computes a snapshot digest, and writes `scan.json` under the scan directory. Later tools append the draft, candidates, validations, attack paths, review items, and saved artifacts, with a per-scan queue serializing mutations. Completion re-resolves the target, rejects a changed digest, checks the draft and coverage contract, builds the findings, coverage, SARIF, and Markdown documents, validates the findings, coverage, and manifest documents against the bundled schemas, and writes the manifest that seals the scan.
112
-
113
- The workbench reaches the same service through `handleRequest` under `/plugins/codex-security`, registered on `webServer` or `httpServer` when one exists. The client half is compiled separately to CommonJS and wrapped for the DSH module loader; it injects into `settings.section` and fetches those routes. Neither half calls a network service, executes target code, or dispatches workers: the sealed manifest records `runtimeStatus: not_executed` and `validationMode: static_source_review`.
114
-
115
- Concurrency is in-process: a per-scan queue serializes read-modify-write operations, and the store writes JSON through same-directory temporary files followed by rename. These are not cross-process locks, so sharing one state directory between DSH processes is unsupported.
116
-
117
- | Source | Contents |
118
- |---|---|
119
- | `cordis.patch.yml` | The layer: one insert entry, row id `codex-security`, three config defaults. |
120
- | `src/index.ts` | Host entry: `apply`, configuration export, bundled-skill discovery and registration. |
121
- | `src/config.ts` | `Config` interface, `DEFAULT_CONFIG`, and the schema ranges enforced at startup. |
122
- | `src/constants.ts` | Package and plugin names, version, route prefix, tool and skill name inventories. |
123
- | `src/service.ts` | Scan lifecycle: target binding, drafts, validations, sealing, findings, exports, and comparisons. |
124
- | `src/store.ts` | State directory resolution, scan directories, index cache, atomic JSON writes, sealed-file sets. |
125
- | `src/target.ts` | Target resolution, file inventory, content hashing, and language and size caps. |
126
- | `src/git.ts` | Git revision, diff, and changed-file queries. |
127
- | `src/tools.ts` | The 29 `codex_security_*` tool definitions and their argument schemas. |
128
- | `src/routes.ts` | `/plugins/codex-security` HTTP routes used by the workbench. |
129
- | `src/contracts.ts` | Finding normalization and fingerprints, coverage, SARIF, and the policy gate. |
130
- | `src/schema.ts` | AJV validation of sealed documents against `schemas/`. |
131
- | `src/types.ts` | Shared scan, finding, coverage, and record types. |
132
- | `src/util.ts` | Filesystem, hashing, timestamp, and JSON helpers. |
133
- | `src/client/index.tsx` | The workbench settings section and its fetch calls. |
134
- | `tests/*.test.mjs` | Unit, real-host integration, and scan-regression suites. |
135
-
136
- </details>
137
-
138
- -----
139
-
140
- <a id="further-exploration"></a>
141
- ## Further Exploration
142
-
143
- - [CHANGELOG.md](CHANGELOG.md) — release history and the unreleased fixes.
144
- - [docs/TOOLS.md](docs/TOOLS.md) — every tool's arguments, return shape, and lifecycle rule.
145
- - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — host lifecycle, target binding, state and sealing, concurrency.
146
- - [docs/ARTIFACTS.md](docs/ARTIFACTS.md) — artifact contracts for scans, findings, coverage, and manifests.
147
- - [docs/SPEC.md](docs/SPEC.md) — product surface, configuration, storage, and workbench routes.
148
- - [docs/VALIDATION.md](docs/VALIDATION.md) — the automated checks and package inspection commands.
149
- - [schemas/](schemas/) — the JSON Schema contracts enforced at sealing.
150
- - [references/](references/) — security guidance used by the scan skills.
151
- - [examples/](examples/) — a completed scan and a legacy completed scan.
152
- - [DeepSeek Harness package-bundle template](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/skills/dsh-doc-writing/templates/package-bundle.md) — the document convention this README follows.
153
- - [Apache-2.0 license](LICENSE).
154
-
155
- -----
156
-
157
- <a id="model-experience"></a>
158
- ## Model Experience
159
-
160
- Indirectly, through the 29 registered tool schemas and ten bundled skill descriptions: their names, descriptions, and argument schemas enter the model's tool and skill catalogs, and scan state otherwise reaches the model only as JSON results of tools the agent calls.
161
-
162
- #### KV Cache effect
163
-
164
- Activating the layer adds 29 tool definitions and ten skill catalog entries to the prompt prefix the host builds for a session, and removing the layer removes the same text. Within a session the catalog is stable, so the added tokens belong to the cached prefix and do not grow per turn; starting, updating, and completing a scan append ordinary tool results and assistant messages after that prefix. The layer injects no system prompt text and owns no model-facing prose beyond the tool and skill descriptions it registers.
165
-
166
- <a id="known-limitations-and-deferred-work"></a>
167
- ## Known Limitations and Deferred Work
168
-
169
- These limits define when the layer does not fit and what it needs from the profile around it.
170
-
171
- - **Records, does not review** — the host stores and validates what an agent submits; it performs no source analysis, cannot verify that a skill was followed, and cannot guarantee that submitted coverage is exhaustive.
172
- - **No execution and no network** — target code is never built, run, or fetched, and a sealed manifest records `runtimeStatus: not_executed` with `validationMode: static_source_review`, so runtime-only weaknesses stay outside the evidence.
173
- - **Deep budgets are recorded, not enforced** — `deepWorkers`, `deepMaxDiscoveryRuns`, the discovery-pass stop rule, and the time budget are stored on the scan for the agent workflow; the host does not dispatch workers or stop a run that exceeds them.
174
- - **One process per state directory** — the layer is added per profile and shares no state between profiles; its locks are in-process, so two DSH processes on one state directory are unsupported and a failed seal can leave intermediate files in a running scan.
175
- - **Sealing is one-way** — agent artifacts can be written only while a scan is running, and `codex_security_save_artifact` refuses sealed and internal paths; triage is the only post-completion mutation, and it never changes the sealed documents.
176
- - **Exports stay local by default** — writing outside the state directory, the process working directory, and the target root requires `allowExportOutsideWorkspace: true`; exporting into the scan storage under `repositories/` is always refused.
177
- - **Native support for file exports** — the matching optional platform binary must be available for file export; if it is missing, export fails closed while scans and in-memory exports remain available. The binary package has no dependency install script.
178
- - **Inventory caps bound the evidence** — `maxFiles` and `maxFileBytes` limit the reviewable inventory, unreadable files become warnings, and the snapshot digest covers only inventoried content, so files outside the caps are outside the evidence.
179
- - **Comparison does not prove a fix** — `codex_security_compare_scans` requires completed scans with a compatible target, mode, and scope, complete coverage, and non-truncated inventories, and it classifies fingerprints only; a missing fingerprint is not a verified fix.
180
-
181
- <a id="dev-note"></a>
182
- ### Dev Note
183
-
184
- <details>
185
- <summary>Working context for maintainers — click to expand</summary>
186
-
187
- `npm run build` removes `lib/`, compiles the host with `tsc -p tsconfig.json`, compiles the client with `tsc -p tsconfig.client.json`, and runs `node scripts/bundle-client.mjs` to wrap `lib/client.js` for the DSH module loader. `npm test` builds first and then runs `node --test tests/*.test.mjs`; `npm run typecheck` runs both compiler projects with `--noEmit`; `npm pack --dry-run` lists the published files. Node.js 22.19 or newer is required by `engines`, and the host needs `@deepseek-ai/cordis` (~4.1.0) and `@deepseek-ai/dsh-skill` (>=0.2.2-rc.2 <0.3.0) as peer dependencies, with the pinned DSH 0.2.2-rc.2 packages in `devDependencies` backing the host integration test. The compiled `lib/` output is tracked and CI checks that a rebuild leaves it unchanged, so edit `src/` and rebuild rather than patching `lib/`. Scan state under the profile's `data/codex-security` directory is user data: `index.json` is rebuildable, `scan-manifest.json` seals each completed scan, and deleting sealed files destroys the evidence the manifest describes.
188
-
189
- </details>
1
+ ---
2
+ description: "An artifact-backed security review layer for a dsh profile: 31 host tools, 16 bundled skills, and a Web workbench that seal schema-validated scans, findings, coverage, and exports under the profile data directory."
3
+ kind: "package-bundle"
4
+ ---
5
+
6
+ # @lornatang/dsh-codex-security
7
+
8
+ English | [中文](README.zh.md)
9
+
10
+ ## Summary
11
+
12
+ `dsh-codex-security` adds a reproducible security review workflow to a dsh profile. It registers 31 `codex_security_*` host tools, 16 bundled skills, and a Codex Security section in the Web GUI that lists scans, findings, coverage, and exports. The `add` command inserts one patch row into the profile and `remove` takes it out. The bundle records and validates agent reviews and can coordinate independent Deep workers. It never executes target code, and completed scans seal immutable artifacts under the profile data directory.
13
+
14
+ ## Table of Contents
15
+
16
+ - [Use this package](#use-this-package)
17
+ - [Understand the implementation](#understand-the-implementation)
18
+ - [Further Exploration](#further-exploration)
19
+ - [Model Experience](#model-experience)
20
+ - [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
21
+ - [Dev Note](#dev-note)
22
+
23
+ -----
24
+
25
+ <a id="use-this-package"></a>
26
+ ## Use this package
27
+
28
+ The layer gives an agent a durable place to record a security review and gives the profile a Web panel to read and export the result: every scan binds its target, revision, and scope, keeps candidates and validations between turns, and seals a schema-checked artifact set on disk.
29
+
30
+ ### Install into a profile
31
+
32
+ ```text
33
+ dsh plugin --profile <name> add @lornatang/dsh-codex-security
34
+ dsh plugin --profile <name> remove @lornatang/dsh-codex-security
35
+ ```
36
+
37
+ For the GitHub 0.1.8 release, use `dsh plugin --profile <name> add https://github.com/Lornatang/dsh-codex-security/releases/download/v0.1.8/lornatang-dsh-codex-security-0.1.8.tgz`. The npm registry version may be older.
38
+
39
+ The `add` command composes the layer into the profile: the profile's `cordis.patch.yml` gains an insert entry, row id `codex-security`, whose `config` starts from the bundle defaults `maxFiles: 5000`, `maxFileBytes: 1048576`, and `defaultMode: standard`; every other field takes its default from `src/config.ts`. The package manifest points `dsh.bundle.patch` at that document. The `remove` command deletes the row and leaves scans already written under the profile data directory untouched.
40
+
41
+ Restart DSH after installing or removing, because the row is composed when the profile starts. On start the plugin logs `codex-security: registered 16 skills` and `codex-security: ready (state dir will resolve on first scan)`, and the Web GUI gains a Codex Security entry under Settings; profiles that do not run the Web client still receive the tools and skills.
42
+
43
+ A new profile starts with no scans. The first request that touches the store — the workbench status request or `codex_security_inspect_setup` — resolves the state directory and creates `<stateDir>/repositories/`; a scan record appears only after one of the start tools runs, and the plugin itself reviews nothing.
44
+
45
+ Scans live under `<stateDir>/repositories/<repoKey>/scans/<scanId>/`, where `repoKey` is the first 16 hexadecimal characters of the target root's SHA-256 and `scanId` is `cs_` plus 24 hexadecimal characters; `<stateDir>` defaults to `data/codex-security` next to the profile's `cordis.patch.yml` (for the shipped Web profile, `$DSH_HOME/profiles/web/data/codex-security`). `scan.json` holds the bound target, scope, inventory, progress, and diff list; `index.json` is a rebuildable list cache. Completion requires a draft submitted with `complete: true`, at least one coverage surface, a final disposition for every candidate and every bound diff file, and an unchanged snapshot digest; the plugin then validates the findings, coverage, and manifest documents against `schemas/`, records hashes in `scan-manifest.json`, and seals the scan. Sealed artifacts are immutable, triage is stored separately and stays editable, and exports default to `<stateDir>/exports/<scanId>.<format>`.
46
+
47
+ Repeated default exports receive a numbered suffix; an explicitly supplied output path must not already exist.
48
+
49
+ ### What you get
50
+
51
+ The package owns three surfaces in the composed profile: 31 host tools, 16 skills, and one workbench section in the Web GUI. [docs/TOOLS.md](docs/TOOLS.md) documents each tool's arguments and return shape; [docs/CODEX-COMPATIBILITY.md](docs/CODEX-COMPATIBILITY.md) compares the implementation with Codex Security.
52
+
53
+ - **Setup and target inspection:** `codex_security_inspect_setup`, `codex_security_inspect_target`.
54
+ - **Scan lifecycle:** `codex_security_start_scan`, `codex_security_start_standard_scan`, `codex_security_start_prompt_only_scan`, `codex_security_start_deep_scan`, `codex_security_resume_deep_scan`, `codex_security_get_deep_scan_status`, `codex_security_get_scan_context`, `codex_security_update_scan_context`, `codex_security_update_scan_progress`.
55
+ - **Discovery and candidates:** `codex_security_record_discovery_candidates`, `codex_security_list_candidates`.
56
+ - **Validation:** `codex_security_record_candidate_validations`, `codex_security_record_candidate_attack_paths`.
57
+ - **Draft and sealing:** `codex_security_record_scan_draft`, `codex_security_complete_scan`, `codex_security_fail_scan`, `codex_security_cancel_scan`.
58
+ - **Agent artifacts:** `codex_security_save_artifact`, `codex_security_read_artifact`.
59
+ - **Findings and triage:** `codex_security_list_findings`, `codex_security_set_finding_triage`, `codex_security_set_finding_remediation`.
60
+ - **Diff review:** `codex_security_prepare_review_items`, `codex_security_list_review_items`, `codex_security_update_review_item`.
61
+ - **Review and comparison:** `codex_security_list_scans`, `codex_security_get_scan`, `codex_security_compare_scans`.
62
+ - **Export:** `codex_security_export_findings`.
63
+
64
+ The skill catalog gains 16 entries, each loaded from `skills/<name>/SKILL.md` at startup with `source: bundled` and both model and user invocation: `security-scan`, `security-diff-scan`, `deep-security-scan`, `fix-finding`, `verify-fix`, `triage-finding`, `threat-model`, `track-findings`, `resolve-dependency-alert`, `vulnerability-writeup`, `assess-patch-risk`, `attack-path-analysis`, `define-security-policy`, `finding-discovery`, `propose-security-hardening`, and `validation`; [skills/](skills/) holds the workflow text for each.
65
+
66
+ The Web GUI gains one `settings.section` row, id `codex-security`, order 41, label Codex Security, registered by this package's client half (`src/client/index.tsx`, shipped as `lib/client.js`) through `@deepseek-ai/dsh-client-ui-slots` and `@deepseek-ai/dsh-client-ui-settings`. The panel shows the version, the resolved state directory, and scan and finding counts; it lists scans with status and age, and opens the selected scan's Overview, Findings, Coverage, and Artifacts & exports panels, including a triage selector and download links for SARIF, JSON, CSV, and Markdown. The panel reads the same service through HTTP routes under `/plugins/codex-security`.
67
+
68
+ ### Configuration
69
+
70
+ The bundle ships the row below, so a profile only lists what differs from it; the profile's own entry is applied after the layer and wins. The loader validates each field against `src/config.ts` and rejects an invalid value at startup instead of substituting a default.
71
+
72
+ ```yaml
73
+ # $DSH_HOME/profiles/web/cordis.patch.yml
74
+ - id: codex-security
75
+ config:
76
+ maxFiles: 5000
77
+ maxFileBytes: 1048576
78
+ defaultMode: standard
79
+ failOnSeverity: high
80
+ allowExportOutsideWorkspace: false
81
+ maxScanAgeDays: 30
82
+ deepWorkers: 4
83
+ deepMaxDiscoveryRuns: 40
84
+ # stateDir: /var/lib/dsh/codex-security
85
+ ```
86
+
87
+ | Field | Default | Meaning |
88
+ |---|---|---|
89
+ | `stateDir` | empty | Directory that holds scans and exports. Empty resolves to `data/codex-security` next to the profile's `cordis.patch.yml`, or to `$DSH_HOME/profiles/web/data/codex-security` when no profile patch path is available. |
90
+ | `maxFiles` | `5000` | Files inventoried per target, 1–200000; truncation is recorded as a scan warning. |
91
+ | `maxFileBytes` | `1048576` | Per-file size cap for the reviewable inventory, 1024–67108864 bytes. |
92
+ | `defaultMode` | `standard` | Mode used by `codex_security_start_scan`: `standard`, `prompt-only`, or `deep`. |
93
+ | `failOnSeverity` | `high` | Policy gate threshold: `informational`, `low`, `medium`, `high`, `critical`, or `off`. |
94
+ | `allowExportOutsideWorkspace` | `false` | Permits exports outside the state directory, the process working directory, and the target root. |
95
+ | `maxScanAgeDays` | `30` | Age at which the workbench marks a scan as older than the policy window, 1–3650 days. |
96
+ | `deepWorkers` | `4` | Maximum concurrent Deep workers, 1–32. |
97
+ | `deepMaxDiscoveryRuns` | `40` | Maximum Deep discovery attempts, 1–10000. |
98
+
99
+ ### Automatic Deep scans
100
+
101
+ Call `codex_security_start_deep_scan` to start independent workers; keep the returned `recoveryClaim` private. Check `codex_security_get_deep_scan_status`, and resume with `codex_security_resume_deep_scan` after a process exits. The original session can resume without the claim; another session needs it for resume or cancellation. `workers`, `maxDiscoveryRuns`, `stopAfterNoNew`, and `maxTimeMinutes` bound orchestration. Interrupted attempts consume the run budget. The target directory identity is fixed at start; file contents are bound during the asynchronous initialization phase. The configured DSH model provider receives source text and may use the network.
102
+
103
+ Automatic mode requires the local DSH `spawn` provider, agent-preset registry, native executor, and matching optional filesystem binary. The standard Web profile supplies the first three; profiles without them fail closed. Automatic Deep accepts repository or directory snapshots, not diffs. Use `manual: true` for the manual workflow. Workers can only read verified, bound source chunks and submit structured output. A zero-finding result requires a complete worker with accepted full-file reads; a receipt proves delivery rather than comprehension.
104
+
105
+ -----
106
+
107
+ <a id="understand-the-implementation"></a>
108
+ ## Understand the implementation
109
+
110
+ <details>
111
+ <summary>Implementation internals — click to expand</summary>
112
+
113
+ The layer is one patch row: an `insert` of id `codex-security`, package name `@lornatang/dsh-codex-security`, and three config values. Nothing is platform-gated on the host side; the manifest's `dsh.client.platform: web` scopes only the client bundle, while the host plugin registers tools and skills in any profile that injects them.
114
+
115
+ Cordis must inject `tools` and `skills` before `apply` runs. `apply` builds a `SecurityService` from the resolved config and the profile patch path, then registers the 31 tools, discovers and registers the 16 bundled skills from `skills/*/SKILL.md`, and binds optional HTTP routes, each in a disposal-aware effect. The state directory is not created at startup; `ScanStore.init` creates it on the first store access.
116
+
117
+ A start tool resolves the target, binds revisions or diff facts, inventories reviewable files within the caps, computes a snapshot digest, and writes `scan.json` under the scan directory. Later tools append the draft, candidates, validations, attack paths, review items, and saved artifacts, with a per-scan queue serializing mutations. Completion re-resolves the target, rejects a changed digest, checks the draft and coverage contract, builds the findings, coverage, SARIF, and Markdown documents, validates the findings, coverage, and manifest documents against the bundled schemas, and writes the manifest that seals the scan.
118
+
119
+ The workbench reaches the same service through `handleRequest` under `/plugins/codex-security`, registered on `webServer` or `httpServer` when one exists. The client half is compiled separately to CommonJS and wrapped for the DSH module loader; it injects into `settings.section` and fetches those routes. The coordinator uses the configured DSH model provider to dispatch isolated static-review workers; the provider may use the network. Workers cannot execute target code.
120
+
121
+ SQLite OS locks serialize campaign ownership, scan mutations and index updates across processes. JSON files use same-directory atomic replacement. Shared state requires a trusted local directory on a filesystem with reliable SQLite locking; individual files are atomic but a full seal is not one transaction.
122
+
123
+ | Source | Contents |
124
+ |---|---|
125
+ | `cordis.patch.yml` | The layer: one insert entry, row id `codex-security`, three config defaults. |
126
+ | `src/index.ts` | Host entry: `apply`, configuration export, bundled-skill discovery and registration. |
127
+ | `src/config.ts` | `Config` interface, `DEFAULT_CONFIG`, and the schema ranges enforced at startup. |
128
+ | `src/constants.ts` | Package and plugin names, version, route prefix, tool and skill name inventories. |
129
+ | `src/service.ts` | Scan lifecycle: target binding, drafts, validations, sealing, findings, exports, and comparisons. |
130
+ | `src/store.ts` | State directory resolution, scan directories, index, atomic JSON writes, sealed-file sets. |
131
+ | `src/deep-*.ts`, `src/secure-read.ts`, `src/state-lock.ts` | Deep orchestration, isolated worker reads and cross-process locks. |
132
+ | `src/target.ts` | Target resolution, file inventory, content hashing, and language and size caps. |
133
+ | `src/git.ts` | Git revision, diff, and changed-file queries. |
134
+ | `src/tools.ts` | The 31 `codex_security_*` tool definitions and their argument schemas. |
135
+ | `src/routes.ts` | `/plugins/codex-security` HTTP routes used by the workbench. |
136
+ | `src/contracts.ts` | Finding normalization and fingerprints, coverage, SARIF, and the policy gate. |
137
+ | `src/schema.ts` | AJV validation of sealed documents against `schemas/`. |
138
+ | `src/types.ts` | Shared scan, finding, coverage, and record types. |
139
+ | `src/util.ts` | Filesystem, hashing, timestamp, and JSON helpers. |
140
+ | `src/client/index.tsx` | The workbench settings section and its fetch calls. |
141
+ | `tests/*.test.mjs` | Unit, real-host integration, and scan-regression suites. |
142
+
143
+ </details>
144
+
145
+ -----
146
+
147
+ <a id="further-exploration"></a>
148
+ ## Further Exploration
149
+
150
+ - [CHANGELOG.md](CHANGELOG.md) — release history and the unreleased fixes.
151
+ - [docs/TOOLS.md](docs/TOOLS.md) — every tool's arguments, return shape, and lifecycle rule.
152
+ - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — host lifecycle, target binding, state and sealing, concurrency.
153
+ - [docs/ARTIFACTS.md](docs/ARTIFACTS.md) — artifact contracts for scans, findings, coverage, and manifests.
154
+ - [docs/SPEC.md](docs/SPEC.md) — product surface, configuration, storage, and workbench routes.
155
+ - [docs/VALIDATION.md](docs/VALIDATION.md) — the automated checks and package inspection commands.
156
+ - [schemas/](schemas/) — the JSON Schema contracts enforced at sealing.
157
+ - [references/](references/) — security guidance used by the scan skills.
158
+ - [examples/](examples/) — a completed scan and a legacy completed scan.
159
+ - [DeepSeek Harness package-bundle template](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/skills/dsh-doc-writing/templates/package-bundle.md) — the document convention this README follows.
160
+ - [Apache-2.0 license](LICENSE).
161
+
162
+ -----
163
+
164
+ <a id="model-experience"></a>
165
+ ## Model Experience
166
+
167
+ Indirectly, through the 31 registered tool schemas and 16 bundled skill descriptions: their names, descriptions, and argument schemas enter the model's tool and skill catalogs, and scan state otherwise reaches the model only as JSON results of tools the agent calls.
168
+
169
+ #### KV Cache effect
170
+
171
+ Activating the layer adds 31 tool definitions and 16 skill catalog entries to the prompt prefix the host builds for a session, and removing the layer removes the same text. Within a session the catalog is stable, so the added tokens belong to the cached prefix and do not grow per turn; starting, updating, and completing a scan append ordinary tool results and assistant messages after that prefix. Automatic workers also receive a focused review prompt and the verified source chunks they request.
172
+
173
+ <a id="known-limitations-and-deferred-work"></a>
174
+ ## Known Limitations and Deferred Work
175
+
176
+ These limits define when the layer does not fit and what it needs from the profile around it.
177
+
178
+ - **Model review** — the host stores and validates what agents submit; it cannot prove that a model understood every file or that coverage is exhaustive.
179
+ - **Static review** — restricted workers do not build or execute target code. The configured model provider may use the network, and runtime-only weaknesses remain outside this evidence.
180
+ - **Deep budgets** — automatic mode limits workers, attempts, no-new reviews and elapsed time; it does not cap model tokens or monetary cost. Manual mode records advisory limits.
181
+ - **Local state** — cross-process coordination requires trusted local storage with reliable SQLite locks. A failed seal can leave intermediate files in a running scan.
182
+ - **Sealing is one-way** — agent artifacts can be written only while a scan is running, and `codex_security_save_artifact` refuses sealed and internal paths; triage is the only post-completion mutation, and it never changes the sealed documents.
183
+ - **Exports stay local by default** — writing outside the state directory, the process working directory, and the target root requires `allowExportOutsideWorkspace: true`; exporting into the scan storage under `repositories/` is always refused.
184
+ - **Native support for file exports** — the matching optional platform binary must be available for file export; if it is missing, file export and automatic worker source reads fail closed; manual scans and in-memory exports remain available. The binary package has no dependency install script.
185
+ - **Inventory caps bound the evidence** — `maxFiles` and `maxFileBytes` limit the reviewable inventory, unreadable files become warnings, and the snapshot digest covers only inventoried content, so files outside the caps are outside the evidence.
186
+ - **Comparison does not prove a fix** — `codex_security_compare_scans` requires completed scans with a compatible target, mode, and scope, complete coverage, and non-truncated inventories. It compares fingerprints and uniquely matched legacy identities; a missing fingerprint is not a verified fix.
187
+
188
+ <a id="dev-note"></a>
189
+ ### Dev Note
190
+
191
+ <details>
192
+ <summary>Working context for maintainers — click to expand</summary>
193
+
194
+ `npm run build` removes `lib/`, compiles the host with `tsc -p tsconfig.json`, compiles the client with `tsc -p tsconfig.client.json`, and runs `node scripts/bundle-client.mjs` to wrap `lib/client.js` for the DSH module loader. `npm test` builds first and then runs `node --test tests/*.test.mjs`; `npm run typecheck` runs both compiler projects with `--noEmit`; `npm pack --dry-run` lists the published files. Node.js 22.19 or newer is required by `engines`, and the host needs `@deepseek-ai/cordis` (~4.1.0) and `@deepseek-ai/dsh-skill` (>=0.2.2-rc.2 <0.3.0) as peer dependencies, with the pinned DSH 0.2.2-rc.2 packages in `devDependencies` backing the host integration test. The compiled `lib/` output is tracked and CI checks that a rebuild leaves it unchanged, so edit `src/` and rebuild rather than patching `lib/`. Scan state under the profile's `data/codex-security` directory is user data: `index.json` is rebuildable, `scan-manifest.json` seals each completed scan, and deleting sealed files destroys the evidence the manifest describes.
195
+
196
+ </details>