@lornatang/dsh-codex-security 0.1.12 → 0.1.13

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 (40) hide show
  1. package/CHANGELOG.md +5 -0
  2. package/README.md +1 -1
  3. package/README.zh.md +1 -1
  4. package/docs/ARCHITECTURE.md +59 -59
  5. package/docs/ARTIFACTS.md +49 -49
  6. package/docs/CODEX-COMPATIBILITY.md +17 -17
  7. package/docs/SPEC.md +43 -43
  8. package/docs/TOOLS.md +364 -364
  9. package/docs/VALIDATION.md +33 -33
  10. package/docs/superpowers/plans/2026-11-16-deep-scan.md +71 -71
  11. package/docs/superpowers/specs/2026-11-16-deep-scan-design.md +31 -31
  12. package/lib/client.js +6 -1
  13. package/lib/constants.js +1 -1
  14. package/lib/deep-coordinator.js +80 -55
  15. package/lib/git.js +44 -8
  16. package/lib/service.js +65 -29
  17. package/lib/store.js +78 -39
  18. package/lib/target.js +27 -11
  19. package/lib/types/constants.d.ts +1 -1
  20. package/lib/types/deep-coordinator.d.ts +2 -8
  21. package/lib/types/git.d.ts +4 -0
  22. package/lib/types/index.d.ts +1 -1
  23. package/lib/types/service.d.ts +5 -3
  24. package/lib/types/store.d.ts +6 -1
  25. package/lib/types/target.d.ts +6 -2
  26. package/lib/types/util.d.ts +1 -0
  27. package/lib/util.js +18 -15
  28. package/package.json +1 -1
  29. package/schemas/coverage.schema.json +136 -136
  30. package/skills/README.md +122 -122
  31. package/skills/assess-patch-risk/SKILL.md +10 -10
  32. package/skills/attack-path-analysis/SKILL.md +10 -10
  33. package/skills/deep-security-scan/SKILL.md +15 -15
  34. package/skills/define-security-policy/SKILL.md +10 -10
  35. package/skills/finding-discovery/SKILL.md +10 -10
  36. package/skills/fix-finding/SKILL.md +14 -14
  37. package/skills/propose-security-hardening/SKILL.md +10 -10
  38. package/skills/track-findings/SKILL.md +12 -12
  39. package/skills/validation/SKILL.md +10 -10
  40. package/skills/verify-fix/SKILL.md +14 -14
package/CHANGELOG.md CHANGED
@@ -1,5 +1,10 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.1.13] - 2026-11-19
4
+
5
+ - Anchor revision-only scan evidence to the bound Git revision.
6
+ - Publish scan artifacts only once the scan is completed, and write Deep worker sidecars only when the worker result changes.
7
+
3
8
  ## [0.1.12] - 2026-11-19
4
9
 
5
10
  - Read chunked evidence from the already verified worker text cache instead of re-reading and hashing the whole file per chunk.
package/README.md CHANGED
@@ -34,7 +34,7 @@ dsh plugin --profile <name> add @lornatang/dsh-codex-security
34
34
  dsh plugin --profile <name> remove @lornatang/dsh-codex-security
35
35
  ```
36
36
 
37
- For the GitHub 0.1.12 release, use `dsh plugin --profile <name> add https://github.com/Lornatang/dsh-codex-security/releases/download/v0.1.12/lornatang-dsh-codex-security-0.1.12.tgz`. The npm registry version may be older.
37
+ For the GitHub 0.1.13 release, use `dsh plugin --profile <name> add https://github.com/Lornatang/dsh-codex-security/releases/download/v0.1.13/lornatang-dsh-codex-security-0.1.13.tgz`.
38
38
 
39
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
40
 
package/README.zh.md CHANGED
@@ -34,7 +34,7 @@ dsh plugin --profile <name> add @lornatang/dsh-codex-security
34
34
  dsh plugin --profile <name> remove @lornatang/dsh-codex-security
35
35
  ```
36
36
 
37
- 安装 GitHub 上的 0.1.12 版本,请运行 `dsh plugin --profile <name> add https://github.com/Lornatang/dsh-codex-security/releases/download/v0.1.12/lornatang-dsh-codex-security-0.1.12.tgz`。npm 仓库中的版本可能较旧。
37
+ 安装 GitHub 上的 0.1.13 版本,请运行 `dsh plugin --profile <name> add https://github.com/Lornatang/dsh-codex-security/releases/download/v0.1.13/lornatang-dsh-codex-security-0.1.13.tgz`。
38
38
 
39
39
  `add` 命令把这一层组合进 profile:profile 的 `cordis.patch.yml` 中新增一条 insert 条目,row id 为 `codex-security`,其 `config` 从本包默认值 `maxFiles: 5000`、`maxFileBytes: 1048576`、`defaultMode: standard` 开始;其余字段取 `src/config.ts` 中的默认值。包清单把 `dsh.bundle.patch` 指向该文档。`remove` 命令删除该条目,已经写入 profile 数据目录的扫描保持不变。
40
40
 
@@ -1,59 +1,59 @@
1
- # Architecture
2
-
3
- The package is a DSH host plugin with a separately compiled web client. Its scan service records agent reviews; automatic Deep coordinates independent DSH model workers and seals their validated results.
4
-
5
- ## Repository layout
6
-
7
- ```text
8
- package.json, package-lock.json Package metadata and locked dependencies
9
- cordis.patch.yml DSH bundle entry
10
- src/index.ts Host entry and bundled-skill registration
11
- src/config.ts, constants.ts Configuration and public names
12
- src/target.ts, git.ts Target binding, inventory and Git queries
13
- src/service.ts, store.ts Scan operations, lifecycle and persistence
14
- src/deep-*.ts, secure-read.ts Deep coordinator, worker isolation and source binding
15
- src/state-lock.ts SQLite cross-process locks
16
- src/contracts.ts, schema.ts Artifact construction and schema validation
17
- src/tools.ts, routes.ts Agent tools and HTTP routes
18
- src/client/index.tsx Workbench settings section
19
- skills/ Sixteen agent workflows
20
- schemas/ JSON Schema contracts
21
- references/ Adapted reference material
22
- examples/ Illustrative artifacts
23
- scripts/ Client bundling
24
- lib/ Generated host/client output, committed for distribution
25
- tests/ Node tests and DSH host integration tests
26
- docs/ Project documentation
27
- ```
28
-
29
- The host build emits ESM and declarations to `lib/`; the client build emits CommonJS and wraps it in the DSH module loader format. `npm test` rebuilds both. CI checks that a rebuild leaves the tracked `lib/` files unchanged. The npm package includes `lib`, the DSH patch, skills, schemas, references, documentation and examples; it excludes source and tests.
30
-
31
- ## Host lifecycle
32
-
33
- The entry exports a default plugin object and named `name`, `inject`, `Config` and `apply`. Cordis must inject both `tools` and `skills` before `apply` runs. The plugin registers its tools, 16 skills with `source: bundled`, and optional HTTP routes in disposal-aware effects. The host adapter validates tool inputs and returns lossless JSON values.
34
-
35
- ## Target binding
36
-
37
- A target must be an existing directory. Git subdirectory targets remain restricted to that subdirectory; non-Git include paths also match descendants. A diff scan binds the resolved base and head, scope and complete changed-file list at creation. Working-tree diffs include staged, unstaged and untracked files; revision-only diffs are bound to immutable Git revisions.
38
-
39
- A snapshot digest covers the bound revision and diff list, plus the contents of inventoried reviewable files for worktree and directory scans. Files are streamed to the hash; missing or unreadable files are recorded as warnings. The inventory cap and default exclusions limit what the digest covers. Completion re-resolves the target and rejects a changed digest.
40
-
41
- ## State and sealing
42
-
43
- State lives in `<stateDir>/repositories/<repoKey>/scans/<scanId>/`; `repoKey` is derived from the canonical target root and the scan ID is `cs_` plus 24 hex characters. `scan.json` records state, scope, inventory, progress and the bound diff list. `index.json` is a rebuildable list cache. Checkpoints, candidates, validations, attack paths and review items are stored alongside it.
44
-
45
- A scan starts as `running` and may become `completed`, `failed` or `canceled`. Completion requires an explicit `complete: true` draft, at least one coverage surface, a disposition for each candidate, a disposition for every bound diff item, and an unchanged target. A deferred candidate must also be represented in coverage. Findings, coverage and manifest documents are validated against the bundled schemas before the seal is accepted.
46
-
47
- The manifest hashes `findings.json`, `coverage.json`, `report.md`, `sarif.json`, an optional threat model and every agent-saved supporting artifact. Artifacts cannot be written after the scan leaves `running`, and exports cannot target scan storage. Triage is intentionally separate from the seal and can be updated after completion.
48
-
49
- Comparison requires completed scans with compatible target, mode and scope, complete coverage and non-truncated inventories. It compares fingerprints and uniquely matched legacy identities; a reviewer must verify the source before declaring a fix.
50
-
51
- ## Concurrency and limits
52
-
53
- A per-scan queue and SQLite OS-backed locks serialize read-modify-write operations across processes. A separate global lock protects index writes, and a campaign lock admits only one live coordinator. Lock databases persist and are released by the OS after a process exits; the trusted state directory must use a local filesystem with reliable SQLite locking. Individual JSON files use same-directory atomic replacement, not a multi-file transaction. A failed seal can leave intermediate files, but completed status is recorded only after the manifest is written.
54
-
55
- The HTTP routes and web workbench share the same service. Export paths outside the workspace or state directory require explicit configuration. The application treats target content as untrusted, but it cannot guarantee that an agent follows a skill or that the submitted coverage is exhaustive.
56
-
57
- ## Automatic Deep coordination
58
-
59
- A durable journal holds the immutable target and per-file digests, deadline, run attempts and hashed recovery claim. A local fresh-context `spawn` activation uses a dedicated persistent preset whose guard permits only bounded source reads and structured output. Reads use pinned handles, verify content hashes and count coverage only after the model-facing output is accepted; symlinked source components are rejected. One complete worker must receive every bound file before a zero-finding result can be sealed. Conflicting findings and failed or interrupted workers remain visible as partial coverage. Recovery needs the original live session or the returned claim; it reconciles saved child results and counts interrupted attempts. The workflow has no hard token or monetary cap.
1
+ # Architecture
2
+
3
+ The package is a DSH host plugin with a separately compiled web client. Its scan service records agent reviews; automatic Deep coordinates independent DSH model workers and seals their validated results.
4
+
5
+ ## Repository layout
6
+
7
+ ```text
8
+ package.json, package-lock.json Package metadata and locked dependencies
9
+ cordis.patch.yml DSH bundle entry
10
+ src/index.ts Host entry and bundled-skill registration
11
+ src/config.ts, constants.ts Configuration and public names
12
+ src/target.ts, git.ts Target binding, inventory and Git queries
13
+ src/service.ts, store.ts Scan operations, lifecycle and persistence
14
+ src/deep-*.ts, secure-read.ts Deep coordinator, worker isolation and source binding
15
+ src/state-lock.ts SQLite cross-process locks
16
+ src/contracts.ts, schema.ts Artifact construction and schema validation
17
+ src/tools.ts, routes.ts Agent tools and HTTP routes
18
+ src/client/index.tsx Workbench settings section
19
+ skills/ Sixteen agent workflows
20
+ schemas/ JSON Schema contracts
21
+ references/ Adapted reference material
22
+ examples/ Illustrative artifacts
23
+ scripts/ Client bundling
24
+ lib/ Generated host/client output, committed for distribution
25
+ tests/ Node tests and DSH host integration tests
26
+ docs/ Project documentation
27
+ ```
28
+
29
+ The host build emits ESM and declarations to `lib/`; the client build emits CommonJS and wraps it in the DSH module loader format. `npm test` rebuilds both. CI checks that a rebuild leaves the tracked `lib/` files unchanged. The npm package includes `lib`, the DSH patch, skills, schemas, references, documentation and examples; it excludes source and tests.
30
+
31
+ ## Host lifecycle
32
+
33
+ The entry exports a default plugin object and named `name`, `inject`, `Config` and `apply`. Cordis must inject both `tools` and `skills` before `apply` runs. The plugin registers its tools, 16 skills with `source: bundled`, and optional HTTP routes in disposal-aware effects. The host adapter validates tool inputs and returns lossless JSON values.
34
+
35
+ ## Target binding
36
+
37
+ A target must be an existing directory. Git subdirectory targets remain restricted to that subdirectory; non-Git include paths also match descendants. A diff scan binds the resolved base and head, scope and complete changed-file list at creation. Working-tree diffs include staged, unstaged and untracked files; revision-only diffs are bound to immutable Git revisions.
38
+
39
+ A snapshot digest covers the bound revision and diff list, plus the contents of inventoried reviewable files for worktree and directory scans. Files are streamed to the hash; missing or unreadable files are recorded as warnings. The inventory cap and default exclusions limit what the digest covers. Completion re-resolves the target and rejects a changed digest.
40
+
41
+ ## State and sealing
42
+
43
+ State lives in `<stateDir>/repositories/<repoKey>/scans/<scanId>/`; `repoKey` is derived from the canonical target root and the scan ID is `cs_` plus 24 hex characters. `scan.json` records state, scope, inventory, progress and the bound diff list. `index.json` is a rebuildable list cache. Checkpoints, candidates, validations, attack paths and review items are stored alongside it.
44
+
45
+ A scan starts as `running` and may become `completed`, `failed` or `canceled`. Completion requires an explicit `complete: true` draft, at least one coverage surface, a disposition for each candidate, a disposition for every bound diff item, and an unchanged target. A deferred candidate must also be represented in coverage. Findings, coverage and manifest documents are validated against the bundled schemas before the seal is accepted.
46
+
47
+ The manifest hashes `findings.json`, `coverage.json`, `report.md`, `sarif.json`, an optional threat model and every agent-saved supporting artifact. Artifacts cannot be written after the scan leaves `running`, and exports cannot target scan storage. Triage is intentionally separate from the seal and can be updated after completion.
48
+
49
+ Comparison requires completed scans with compatible target, mode and scope, complete coverage and non-truncated inventories. It compares fingerprints and uniquely matched legacy identities; a reviewer must verify the source before declaring a fix.
50
+
51
+ ## Concurrency and limits
52
+
53
+ A per-scan queue and SQLite OS-backed locks serialize read-modify-write operations across processes. A separate global lock protects index writes, and a campaign lock admits only one live coordinator. Lock databases persist and are released by the OS after a process exits; the trusted state directory must use a local filesystem with reliable SQLite locking. Individual JSON files use same-directory atomic replacement, not a multi-file transaction. A failed seal can leave intermediate files, but completed status is recorded only after the manifest is written.
54
+
55
+ The HTTP routes and web workbench share the same service. Export paths outside the workspace or state directory require explicit configuration. The application treats target content as untrusted, but it cannot guarantee that an agent follows a skill or that the submitted coverage is exhaustive.
56
+
57
+ ## Automatic Deep coordination
58
+
59
+ A durable journal holds the immutable target and per-file digests, deadline, run attempts and hashed recovery claim. A local fresh-context `spawn` activation uses a dedicated persistent preset whose guard permits only bounded source reads and structured output. Reads use pinned handles, verify content hashes and count coverage only after the model-facing output is accepted; symlinked source components are rejected. One complete worker must receive every bound file before a zero-finding result can be sealed. Conflicting findings and failed or interrupted workers remain visible as partial coverage. Recovery needs the original live session or the returned claim; it reconciles saved child results and counts interrupted attempts. The workflow has no hard token or monetary cap.
package/docs/ARTIFACTS.md CHANGED
@@ -1,49 +1,49 @@
1
- # Artifact contracts
2
-
3
- A scan is stored at `<stateDir>/repositories/<repoKey>/scans/<scanId>/`. IDs are `cs_` plus 24 lowercase hex characters. The package ships JSON Schemas for findings, coverage and manifests; the host validates all three before accepting a completed seal.
4
-
5
- ## Files
6
-
7
- | File | Purpose | In manifest |
8
- | --- | --- | --- |
9
- | `scan.json` | Internal state, scope, snapshot, progress and diff file list | No |
10
- | `findings.json` | Normalized findings | Yes |
11
- | `coverage.json` | Reviewed surfaces, exclusions and deferred work | Yes |
12
- | `report.md` | Human-readable static review report | Yes |
13
- | `sarif.json` | SARIF 2.1.0 representation | Yes |
14
- | `threat-model.md` | Optional threat model | When present |
15
- | `threatmodel.md` | Codex-compatible threat-model projection | When present |
16
- | Agent-saved artifacts | Writeups and other supporting files | Yes |
17
- | `checkpoints/scan-draft.json` | Most recent draft checkpoint | No |
18
- | `candidates.json`, `validations.json`, `attack-paths.json` | Candidate ledger | No |
19
- | `review-items.json` | Bound diff file dispositions | No |
20
- | `triage.json` | Separately editable finding status and remediation | No |
21
- | `scan-manifest.json` | Seal metadata and hashes of the listed files | The manifest does not hash itself |
22
-
23
- Agent-saved files are scan-relative. Common paths are `findings/<slug>/<slug>.md`, `artifacts/<path>`, `patches/<slug>.patch`, `tests/<slug>-test.md` and `verify/<slug>-verification.md`. Internal scan files and checkpoints cannot be overwritten with `save_artifact`. Supporting artifacts can be written only while a scan is running. Triage is deliberately separate and remains editable after completion.
24
-
25
- ## Findings
26
-
27
- `findings.json` has `documentType: codex-security.findings`, `schemaVersion: 1.0`, the scan ID and a `findings` array. Each normalized finding has a finding ID, occurrence ID, rule ID, identity, fingerprint, title, summary, severity, confidence, taxonomy, locations, remediation and provenance. `taxonomy.cwe` is always an array; a single supplied CWE is normalized to an array and an unspecified CWE becomes `[]`.
28
-
29
- The primary fingerprint is `codex-security/v1:sha256:` followed by the SHA-256 of the algorithm, stable workspace target ID, normalized rule, anchor and optional instance. The default anchor uses the rule, a path slug and a hash of the normalized evidence line; an explicit semantic anchor can be supplied. An unchanged finding keeps its finding ID across scans and receives a new occurrence ID in each scan. Duplicate identities in one draft are rejected; use `identity.instance` to distinguish separate findings.
30
-
31
- Previously sealed scans retain their original fingerprints and IDs. Comparison can match a legacy finding to a new finding when rule, anchor and instance uniquely agree, including when a file moves; it rejects ambiguous legacy matches. Triage remains attached to the original scan. An unsealed legacy checkpoint is upgraded when completed and the returned ID mapping identifies the change.
32
-
33
- ## Coverage
34
-
35
- `coverage.json` records the scan mode, completeness, inventory strategy, include/exclude paths, surfaces, explicit exclusions, deferred work and optional resolved deferred items and open questions. Surface dispositions are `reported`, `no_issue_found`, `rejected`, `not_applicable` and `needs_follow_up`. Receipts must be saved regular files under `artifacts/` and are included in the seal. A partial or unknown review cannot be used to classify findings as closed in a comparison.
36
-
37
- A scan cannot be sealed with an incomplete draft or an empty surface list. Each candidate needs a disposition; a candidate marked deferred must be represented in `reviewState.deferred` by candidate ID or path. Diff scans additionally require a recorded review disposition for every bound changed file. These checks validate the submitted record, not whether an agent actually read the claimed code.
38
-
39
- ## Manifest and snapshot
40
-
41
- `scan-manifest.json` contains producer, status, timestamps, target identity and snapshot digest, scope, findings reference and artifact entries with SHA-256 hashes. The manifest mode uses the coverage mode vocabulary. Optional context is omitted when absent; the host does not claim that inventory counts prove files were reviewed.
42
-
43
- The snapshot identifies the bound revision and diff list and, for directory and working-tree reviews, the content of inventoried reviewable files. It is rechecked on completion. Default exclusions, the inventory cap and unreadable-file warnings limit what it covers. A revision-only diff is tied to immutable Git revisions. The snapshot is an identity for the review scope, not a hash of every byte in the repository.
44
-
45
- ## Drafts, comparison and exports
46
-
47
- `record_scan_draft` replaces the previous checkpoint and projects the current threat model to `threatmodel.md` while the scan is running. It validates normalized findings against the bundled schema; final sealing requires `complete: true`. Scope is fixed when the scan starts. Completed scans may be compared only if target, mode and scope are compatible and their coverage is complete. Findings are classified as `closed`, `new`, or `open` by fingerprint, with unique semantic matching for legacy scans; source review is still required to establish a fix.
48
-
49
- Exports are available as SARIF, JSON, CSV and Markdown for completed scans. They default to `<stateDir>/exports/`; an explicitly requested destination is subject to the configured path policy and cannot be inside scan storage. The files in [examples/](../examples) illustrate the format and are not necessarily byte-for-byte output from this version.
1
+ # Artifact contracts
2
+
3
+ A scan is stored at `<stateDir>/repositories/<repoKey>/scans/<scanId>/`. IDs are `cs_` plus 24 lowercase hex characters. The package ships JSON Schemas for findings, coverage and manifests; the host validates all three before accepting a completed seal.
4
+
5
+ ## Files
6
+
7
+ | File | Purpose | In manifest |
8
+ | --- | --- | --- |
9
+ | `scan.json` | Internal state, scope, snapshot, progress and diff file list | No |
10
+ | `findings.json` | Normalized findings | Yes |
11
+ | `coverage.json` | Reviewed surfaces, exclusions and deferred work | Yes |
12
+ | `report.md` | Human-readable static review report | Yes |
13
+ | `sarif.json` | SARIF 2.1.0 representation | Yes |
14
+ | `threat-model.md` | Optional threat model | When present |
15
+ | `threatmodel.md` | Codex-compatible threat-model projection | When present |
16
+ | Agent-saved artifacts | Writeups and other supporting files | Yes |
17
+ | `checkpoints/scan-draft.json` | Most recent draft checkpoint | No |
18
+ | `candidates.json`, `validations.json`, `attack-paths.json` | Candidate ledger | No |
19
+ | `review-items.json` | Bound diff file dispositions | No |
20
+ | `triage.json` | Separately editable finding status and remediation | No |
21
+ | `scan-manifest.json` | Seal metadata and hashes of the listed files | The manifest does not hash itself |
22
+
23
+ Agent-saved files are scan-relative. Common paths are `findings/<slug>/<slug>.md`, `artifacts/<path>`, `patches/<slug>.patch`, `tests/<slug>-test.md` and `verify/<slug>-verification.md`. Internal scan files and checkpoints cannot be overwritten with `save_artifact`. Supporting artifacts can be written only while a scan is running. Triage is deliberately separate and remains editable after completion.
24
+
25
+ ## Findings
26
+
27
+ `findings.json` has `documentType: codex-security.findings`, `schemaVersion: 1.0`, the scan ID and a `findings` array. Each normalized finding has a finding ID, occurrence ID, rule ID, identity, fingerprint, title, summary, severity, confidence, taxonomy, locations, remediation and provenance. `taxonomy.cwe` is always an array; a single supplied CWE is normalized to an array and an unspecified CWE becomes `[]`.
28
+
29
+ The primary fingerprint is `codex-security/v1:sha256:` followed by the SHA-256 of the algorithm, stable workspace target ID, normalized rule, anchor and optional instance. The default anchor uses the rule, a path slug and a hash of the normalized evidence line; an explicit semantic anchor can be supplied. An unchanged finding keeps its finding ID across scans and receives a new occurrence ID in each scan. Duplicate identities in one draft are rejected; use `identity.instance` to distinguish separate findings.
30
+
31
+ Previously sealed scans retain their original fingerprints and IDs. Comparison can match a legacy finding to a new finding when rule, anchor and instance uniquely agree, including when a file moves; it rejects ambiguous legacy matches. Triage remains attached to the original scan. An unsealed legacy checkpoint is upgraded when completed and the returned ID mapping identifies the change.
32
+
33
+ ## Coverage
34
+
35
+ `coverage.json` records the scan mode, completeness, inventory strategy, include/exclude paths, surfaces, explicit exclusions, deferred work and optional resolved deferred items and open questions. Surface dispositions are `reported`, `no_issue_found`, `rejected`, `not_applicable` and `needs_follow_up`. Receipts must be saved regular files under `artifacts/` and are included in the seal. A partial or unknown review cannot be used to classify findings as closed in a comparison.
36
+
37
+ A scan cannot be sealed with an incomplete draft or an empty surface list. Each candidate needs a disposition; a candidate marked deferred must be represented in `reviewState.deferred` by candidate ID or path. Diff scans additionally require a recorded review disposition for every bound changed file. These checks validate the submitted record, not whether an agent actually read the claimed code.
38
+
39
+ ## Manifest and snapshot
40
+
41
+ `scan-manifest.json` contains producer, status, timestamps, target identity and snapshot digest, scope, findings reference and artifact entries with SHA-256 hashes. The manifest mode uses the coverage mode vocabulary. Optional context is omitted when absent; the host does not claim that inventory counts prove files were reviewed.
42
+
43
+ The snapshot identifies the bound revision and diff list and, for directory and working-tree reviews, the content of inventoried reviewable files. It is rechecked on completion. Default exclusions, the inventory cap and unreadable-file warnings limit what it covers. A revision-only diff is tied to immutable Git revisions. The snapshot is an identity for the review scope, not a hash of every byte in the repository.
44
+
45
+ ## Drafts, comparison and exports
46
+
47
+ `record_scan_draft` replaces the previous checkpoint and projects the current threat model to `threatmodel.md` while the scan is running. It validates normalized findings against the bundled schema; final sealing requires `complete: true`. Scope is fixed when the scan starts. Completed scans may be compared only if target, mode and scope are compatible and their coverage is complete. Findings are classified as `closed`, `new`, or `open` by fingerprint, with unique semantic matching for legacy scans; source review is still required to establish a fix.
48
+
49
+ Exports are available as SARIF, JSON, CSV and Markdown for completed scans. They default to `<stateDir>/exports/`; an explicitly requested destination is subject to the configured path policy and cannot be inside scan storage. The files in [examples/](../examples) illustrate the format and are not necessarily byte-for-byte output from this version.
@@ -1,17 +1,17 @@
1
- # Codex Security compatibility
2
-
3
- This comparison uses the locally installed Codex Security plugin 0.1.32 as the reference. DSH is an independent implementation and its public tools use the `codex_security_*` naming convention. Matching a skill name or document schema does not imply identical execution or coverage.
4
-
5
- | Area | DSH behavior | Remaining difference |
6
- | --- | --- | --- |
7
- | Skills | All 15 reference skill names are registered, plus `resolve-dependency-alert`. Fix and verification workflows can perform work authorized by the user. | Workflow instructions are independently written and adapted to available DSH tools; they are not identical transcripts of the reference workflows. External tracking requires a separate authorized integration. |
8
- | Findings and seal | New scans use the Codex v1 target, finding and occurrence identity algorithm, `coverage.completeness`, `scan.coverageRef`, evidence references, and the canonical threat-model projection. Legacy sealed scans are not rewritten. | A representative completed scan is checked with the reference validator when `CODEX_SECURITY_REFERENCE_ROOT` is supplied; this is not a guarantee for every possible input or historical artifact. |
9
- | Drafts and candidates | Drafts accept `coverage` or DSH `reviewState`. Discovery, validation and attack-path records accept the Codex-style nested data as well as DSH's flat forms and retain the nested evidence. | Tool names and several arguments differ. DSH candidate submission appends and deduplicates rather than replacing the complete candidate set; Codex pagination and handoff claims are not implemented. |
10
- | Deep scan | A durable coordinator launches isolated independent DSH workers, seals Standard child scans, merges findings conservatively and enforces worker, attempt, no-new and time limits. | DSH uses its own model provider and source-only worker tools; it does not reproduce the Codex SDK implementation or enforce token/dollar budgets. Automatic diff scans are unsupported. |
11
- | Lifecycle and state | SQLite locks serialize campaign ownership, scans and indexes across processes. A hashed recovery claim permits authorized takeover. | Resume is explicit and requires a live DSH agent; SQLite locking requires trusted local storage. The claim is not a Codex handoff token. |
12
- | Host integrations | DSH offers its own web workbench, formats and tools. | Codex desktop preflight, SDK worker orchestration, account-specific Daybreak access, and issue-provider integrations depend on the host and are not supplied by this package. |
13
-
14
- DSH seals the evidence submitted by an agent and checks its structural consistency. It cannot independently guarantee the agent reviewed every claimed surface or followed skill instructions. `complete` describes the submitted coverage, not a proof that no vulnerabilities exist.
15
-
16
-
17
- DSH `startActivation` uses a dedicated persistent worker preset and native tool guard. A successful full-file receipt verifies delivery through the DSH tool pipeline, not that a model understood every file or found every issue.
1
+ # Codex Security compatibility
2
+
3
+ This comparison uses the locally installed Codex Security plugin 0.1.32 as the reference. DSH is an independent implementation and its public tools use the `codex_security_*` naming convention. Matching a skill name or document schema does not imply identical execution or coverage.
4
+
5
+ | Area | DSH behavior | Remaining difference |
6
+ | --- | --- | --- |
7
+ | Skills | All 15 reference skill names are registered, plus `resolve-dependency-alert`. Fix and verification workflows can perform work authorized by the user. | Workflow instructions are independently written and adapted to available DSH tools; they are not identical transcripts of the reference workflows. External tracking requires a separate authorized integration. |
8
+ | Findings and seal | New scans use the Codex v1 target, finding and occurrence identity algorithm, `coverage.completeness`, `scan.coverageRef`, evidence references, and the canonical threat-model projection. Legacy sealed scans are not rewritten. | A representative completed scan is checked with the reference validator when `CODEX_SECURITY_REFERENCE_ROOT` is supplied; this is not a guarantee for every possible input or historical artifact. |
9
+ | Drafts and candidates | Drafts accept `coverage` or DSH `reviewState`. Discovery, validation and attack-path records accept the Codex-style nested data as well as DSH's flat forms and retain the nested evidence. | Tool names and several arguments differ. DSH candidate submission appends and deduplicates rather than replacing the complete candidate set; Codex pagination and handoff claims are not implemented. |
10
+ | Deep scan | A durable coordinator launches isolated independent DSH workers, seals Standard child scans, merges findings conservatively and enforces worker, attempt, no-new and time limits. | DSH uses its own model provider and source-only worker tools; it does not reproduce the Codex SDK implementation or enforce token/dollar budgets. Automatic diff scans are unsupported. |
11
+ | Lifecycle and state | SQLite locks serialize campaign ownership, scans and indexes across processes. A hashed recovery claim permits authorized takeover. | Resume is explicit and requires a live DSH agent; SQLite locking requires trusted local storage. The claim is not a Codex handoff token. |
12
+ | Host integrations | DSH offers its own web workbench, formats and tools. | Codex desktop preflight, SDK worker orchestration, account-specific Daybreak access, and issue-provider integrations depend on the host and are not supplied by this package. |
13
+
14
+ DSH seals the evidence submitted by an agent and checks its structural consistency. It cannot independently guarantee the agent reviewed every claimed surface or followed skill instructions. `complete` describes the submitted coverage, not a proof that no vulnerabilities exist.
15
+
16
+
17
+ DSH `startActivation` uses a dedicated persistent worker preset and native tool guard. A successful full-file receipt verifies delivery through the DSH tool pipeline, not that a model understood every file or found every issue.
package/docs/SPEC.md CHANGED
@@ -1,43 +1,43 @@
1
- # Implementation specification
2
-
3
- The project provides an independent DSH implementation of a skill-driven static security review workbench. The authoritative tool parameter list is [TOOLS.md](TOOLS.md), and the artifact contracts are [ARTIFACTS.md](ARTIFACTS.md) and the JSON Schemas under `schemas/`.
4
-
5
- ## Product surface
6
-
7
- - Package: `@lornatang/dsh-codex-security`; plugin and patch row: `codex-security`.
8
- - Host: 31 `codex_security_*` tools and 16 bundled skills. `tools` and `skills` are required Cordis services.
9
- - Client: one **Codex Security** settings section backed by local HTTP routes.
10
- - Scan modes: `standard`, `prompt-only`, `deep`. `codex_security_start_scan` uses the configured default; named start tools select their mode explicitly.
11
- - Automatic Deep dispatches isolated DSH workers, enforces concurrency, attempt, no-new and wall-clock limits, and journals recovery. A manual mode remains available.
12
-
13
- ## Configuration
14
-
15
- | Key | Default | Contract |
16
- | --- | --- | --- |
17
- | `stateDir` | `""` | Override storage; empty uses the active profile data directory. |
18
- | `maxFiles` | `5000` | Inventory cap, from 1 to 200000. |
19
- | `maxFileBytes` | `1048576` | Maximum bytes used to derive one evidence line. |
20
- | `defaultMode` | `standard` | Default for the generic start tool. |
21
- | `failOnSeverity` | `high` | Policy threshold or `off`. |
22
- | `allowExportOutsideWorkspace` | `false` | Permit explicitly requested exports outside permitted roots. |
23
- | `maxScanAgeDays` | `30` | Workbench age warning; no automatic deletion. |
24
- | `deepWorkers` | `4` | Default concurrent worker limit. |
25
- | `deepMaxDiscoveryRuns` | `40` | Default maximum discovery attempts. |
26
-
27
- ## Lifecycle and storage
28
-
29
- A running scan is bound to an existing directory, scope, revision or working-tree snapshot and, for diffs, a changed-file list. The scope cannot be changed in place. The target is rechecked before completion.
30
-
31
- Completion requires a draft marked complete, at least one coverage surface, candidate dispositions, and dispositions for all bound diff files. Explicitly deferred work remains visible in coverage. The plugin validates generated findings, coverage and manifest against the bundled schemas, writes their hashes, then records completed status. Failed and canceled scans are unsealed. Supporting artifacts are immutable after a scan stops running; triage remains editable in a separate record.
32
-
33
- Comparison requires completed scans with matching target root, target kind, scan mode and include/exclude paths. Diff scans must share a base revision. Truncated, deferred, missing or incomplete coverage is not comparable. Fingerprint disappearance alone does not prove remediation.
34
-
35
- State is local. SQLite OS locks serialize campaign ownership, scan mutations and index writes across processes; lock files are never unlinked. The state directory must be trusted and use a local filesystem with reliable SQLite locking. JSON files are individually atomic, not a multi-file transaction. The index can be rebuilt from scan records.
36
-
37
- ## Workbench and routes
38
-
39
- The host registers `/plugins/codex-security` routes for status, configuration, scans, findings, triage, remediation and exports. The client displays scan state, findings, coverage, exports and an age warning based on `maxScanAgeDays`. It uses the DSH `settings.section` slot and does not initiate scans itself.
40
-
41
- ## Security and scope
42
-
43
- The host uses read-only Git queries and does not build or execute the reviewed target. Automatic workers are restricted to verified, bound source reads and structured output; the DSH model provider may use the network. Explicit exports can write outside scan storage according to the configured policy. Skills instruct the agent to treat repository content as untrusted and redact secrets; these are agent-workflow requirements rather than host-enforced guarantees.
1
+ # Implementation specification
2
+
3
+ The project provides an independent DSH implementation of a skill-driven static security review workbench. The authoritative tool parameter list is [TOOLS.md](TOOLS.md), and the artifact contracts are [ARTIFACTS.md](ARTIFACTS.md) and the JSON Schemas under `schemas/`.
4
+
5
+ ## Product surface
6
+
7
+ - Package: `@lornatang/dsh-codex-security`; plugin and patch row: `codex-security`.
8
+ - Host: 31 `codex_security_*` tools and 16 bundled skills. `tools` and `skills` are required Cordis services.
9
+ - Client: one **Codex Security** settings section backed by local HTTP routes.
10
+ - Scan modes: `standard`, `prompt-only`, `deep`. `codex_security_start_scan` uses the configured default; named start tools select their mode explicitly.
11
+ - Automatic Deep dispatches isolated DSH workers, enforces concurrency, attempt, no-new and wall-clock limits, and journals recovery. A manual mode remains available.
12
+
13
+ ## Configuration
14
+
15
+ | Key | Default | Contract |
16
+ | --- | --- | --- |
17
+ | `stateDir` | `""` | Override storage; empty uses the active profile data directory. |
18
+ | `maxFiles` | `5000` | Inventory cap, from 1 to 200000. |
19
+ | `maxFileBytes` | `1048576` | Maximum bytes used to derive one evidence line. |
20
+ | `defaultMode` | `standard` | Default for the generic start tool. |
21
+ | `failOnSeverity` | `high` | Policy threshold or `off`. |
22
+ | `allowExportOutsideWorkspace` | `false` | Permit explicitly requested exports outside permitted roots. |
23
+ | `maxScanAgeDays` | `30` | Workbench age warning; no automatic deletion. |
24
+ | `deepWorkers` | `4` | Default concurrent worker limit. |
25
+ | `deepMaxDiscoveryRuns` | `40` | Default maximum discovery attempts. |
26
+
27
+ ## Lifecycle and storage
28
+
29
+ A running scan is bound to an existing directory, scope, revision or working-tree snapshot and, for diffs, a changed-file list. The scope cannot be changed in place. The target is rechecked before completion.
30
+
31
+ Completion requires a draft marked complete, at least one coverage surface, candidate dispositions, and dispositions for all bound diff files. Explicitly deferred work remains visible in coverage. The plugin validates generated findings, coverage and manifest against the bundled schemas, writes their hashes, then records completed status. Failed and canceled scans are unsealed. Supporting artifacts are immutable after a scan stops running; triage remains editable in a separate record.
32
+
33
+ Comparison requires completed scans with matching target root, target kind, scan mode and include/exclude paths. Diff scans must share a base revision. Truncated, deferred, missing or incomplete coverage is not comparable. Fingerprint disappearance alone does not prove remediation.
34
+
35
+ State is local. SQLite OS locks serialize campaign ownership, scan mutations and index writes across processes; lock files are never unlinked. The state directory must be trusted and use a local filesystem with reliable SQLite locking. JSON files are individually atomic, not a multi-file transaction. The index can be rebuilt from scan records.
36
+
37
+ ## Workbench and routes
38
+
39
+ The host registers `/plugins/codex-security` routes for status, configuration, scans, findings, triage, remediation and exports. The client displays scan state, findings, coverage, exports and an age warning based on `maxScanAgeDays`. It uses the DSH `settings.section` slot and does not initiate scans itself.
40
+
41
+ ## Security and scope
42
+
43
+ The host uses read-only Git queries and does not build or execute the reviewed target. Automatic workers are restricted to verified, bound source reads and structured output; the DSH model provider may use the network. Explicit exports can write outside scan storage according to the configured policy. Skills instruct the agent to treat repository content as untrusted and redact secrets; these are agent-workflow requirements rather than host-enforced guarantees.