@lornatang/dsh-codex-security 0.1.7 → 0.1.9
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.
- package/CHANGELOG.md +32 -0
- package/README.md +29 -22
- package/README.zh.md +28 -21
- package/docs/ARCHITECTURE.md +11 -5
- package/docs/ARTIFACTS.md +6 -3
- package/docs/CODEX-COMPATIBILITY.md +17 -0
- package/docs/SPEC.md +6 -6
- package/docs/TOOLS.md +34 -11
- package/docs/VALIDATION.md +5 -3
- package/docs/superpowers/plans/2026-11-16-deep-scan.md +71 -0
- package/docs/superpowers/specs/2026-11-16-deep-scan-design.md +31 -0
- package/lib/constants.js +3 -3
- package/lib/contracts.js +114 -34
- package/lib/deep-coordinator.js +599 -0
- package/lib/deep-host.js +36 -0
- package/lib/deep-worker.js +254 -0
- package/lib/git.js +26 -22
- package/lib/index.js +23 -1
- package/lib/secure-read.js +229 -0
- package/lib/service.js +403 -62
- package/lib/state-lock.js +71 -0
- package/lib/store.js +33 -15
- package/lib/target.js +40 -14
- package/lib/tools.js +54 -19
- package/lib/types/constants.d.ts +1 -1
- package/lib/types/contracts.d.ts +5 -2
- package/lib/types/deep-coordinator.d.ts +70 -0
- package/lib/types/deep-host.d.ts +32 -0
- package/lib/types/deep-worker.d.ts +110 -0
- package/lib/types/git.d.ts +10 -10
- package/lib/types/index.d.ts +1 -1
- package/lib/types/secure-read.d.ts +15 -0
- package/lib/types/service.d.ts +20 -4
- package/lib/types/state-lock.d.ts +9 -0
- package/lib/types/store.d.ts +5 -2
- package/lib/types/target.d.ts +1 -0
- package/lib/types/tools.d.ts +3 -2
- package/lib/types/types.d.ts +42 -7
- package/lib/types/util.d.ts +4 -0
- package/lib/types/worker-preset.d.ts +18 -0
- package/lib/util.js +158 -14
- package/lib/worker-preset.js +8 -0
- package/package.json +9 -1
- package/schemas/coverage.schema.json +2 -0
- package/skills/README.md +17 -11
- package/skills/assess-patch-risk/SKILL.md +10 -0
- package/skills/attack-path-analysis/SKILL.md +10 -0
- package/skills/deep-security-scan/SKILL.md +8 -109
- package/skills/define-security-policy/SKILL.md +10 -0
- package/skills/finding-discovery/SKILL.md +10 -0
- package/skills/fix-finding/SKILL.md +6 -104
- package/skills/propose-security-hardening/SKILL.md +10 -0
- package/skills/track-findings/SKILL.md +5 -106
- package/skills/validation/SKILL.md +10 -0
- package/skills/verify-fix/SKILL.md +6 -100
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,37 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [0.1.9] - 2026-11-17
|
|
4
|
+
|
|
5
|
+
### Security
|
|
6
|
+
|
|
7
|
+
- Contain evidence reads to the scan target: sanitize and validate finding location paths, rejecting traversal, absolute paths and symlink escapes before reading any host file.
|
|
8
|
+
- Eliminate catastrophic backtracking (ReDoS) in scope glob matching by collapsing nested quantifiers and matching include/exclude globs with a cached linear-time matcher.
|
|
9
|
+
|
|
10
|
+
### Fixed
|
|
11
|
+
|
|
12
|
+
- Read at most the requested byte limit when loading artifacts instead of buffering entire files into memory.
|
|
13
|
+
- Create atomic-write temporary files exclusively (`wx`) with 96-bit random suffixes.
|
|
14
|
+
- Reject option-like Git revision arguments (leading `-`) before invoking `rev-parse`.
|
|
15
|
+
|
|
16
|
+
### Performance
|
|
17
|
+
|
|
18
|
+
- Compile scope globs once and cache them, removing per-file/per-pattern RegExp recompilation during inventory walks.
|
|
19
|
+
|
|
20
|
+
## [0.1.8] - 2026-11-16
|
|
21
|
+
|
|
22
|
+
### Added
|
|
23
|
+
|
|
24
|
+
- Coordinate independent, restricted Deep review workers with bounded concurrency, attempts, no-new stopping and wall-clock time.
|
|
25
|
+
- Persist campaign progress and recovery claims, with authenticated cross-process resume and cancellation.
|
|
26
|
+
- Add Codex-compatible skill workflows and artifact contracts, plus cross-platform worker, recovery and concurrency tests.
|
|
27
|
+
|
|
28
|
+
### Fixed
|
|
29
|
+
|
|
30
|
+
- Bind worker reads and evidence to verified target objects and file snapshots; keep incomplete coverage and conflicting findings visible.
|
|
31
|
+
- Serialize shared indexes and scan mutations across processes and tolerate transient Windows file-sharing conflicts during atomic replacement.
|
|
32
|
+
- Fail closed when target inventory cannot be enumerated or Git metadata cannot be resolved.
|
|
33
|
+
- Use the macOS 26 ARM runner when macOS 15 ARM runners are unavailable.
|
|
34
|
+
|
|
3
35
|
## [0.1.7] - 2026-11-16
|
|
4
36
|
|
|
5
37
|
### Fixed
|
package/README.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: "An artifact-backed security review layer for a dsh profile:
|
|
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
3
|
kind: "package-bundle"
|
|
4
4
|
---
|
|
5
5
|
|
|
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
|
|
|
9
9
|
|
|
10
10
|
## Summary
|
|
11
11
|
|
|
12
|
-
`dsh-codex-security` adds a reproducible security review workflow to a dsh profile. It registers
|
|
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
13
|
|
|
14
14
|
## Table of Contents
|
|
15
15
|
|
|
@@ -34,11 +34,11 @@ 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.
|
|
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
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
|
|
|
41
|
-
Restart DSH after installing or removing, because the row is composed when the profile starts. On start the plugin logs `codex-security: registered
|
|
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
42
|
|
|
43
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
44
|
|
|
@@ -48,10 +48,10 @@ Repeated default exports receive a numbered suffix; an explicitly supplied outpu
|
|
|
48
48
|
|
|
49
49
|
### What you get
|
|
50
50
|
|
|
51
|
-
The package owns three surfaces in the composed profile:
|
|
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
52
|
|
|
53
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`.
|
|
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
55
|
- **Discovery and candidates:** `codex_security_record_discovery_candidates`, `codex_security_list_candidates`.
|
|
56
56
|
- **Validation:** `codex_security_record_candidate_validations`, `codex_security_record_candidate_attack_paths`.
|
|
57
57
|
- **Draft and sealing:** `codex_security_record_scan_draft`, `codex_security_complete_scan`, `codex_security_fail_scan`, `codex_security_cancel_scan`.
|
|
@@ -61,7 +61,7 @@ The package owns three surfaces in the composed profile: 29 host tools, ten skil
|
|
|
61
61
|
- **Review and comparison:** `codex_security_list_scans`, `codex_security_get_scan`, `codex_security_compare_scans`.
|
|
62
62
|
- **Export:** `codex_security_export_findings`.
|
|
63
63
|
|
|
64
|
-
The skill catalog gains
|
|
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
65
|
|
|
66
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
67
|
|
|
@@ -93,8 +93,14 @@ The bundle ships the row below, so a profile only lists what differs from it; th
|
|
|
93
93
|
| `failOnSeverity` | `high` | Policy gate threshold: `informational`, `low`, `medium`, `high`, `critical`, or `off`. |
|
|
94
94
|
| `allowExportOutsideWorkspace` | `false` | Permits exports outside the state directory, the process working directory, and the target root. |
|
|
95
95
|
| `maxScanAgeDays` | `30` | Age at which the workbench marks a scan as older than the policy window, 1–3650 days. |
|
|
96
|
-
| `deepWorkers` | `4` |
|
|
97
|
-
| `deepMaxDiscoveryRuns` | `40` |
|
|
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.
|
|
98
104
|
|
|
99
105
|
-----
|
|
100
106
|
|
|
@@ -106,13 +112,13 @@ The bundle ships the row below, so a profile only lists what differs from it; th
|
|
|
106
112
|
|
|
107
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.
|
|
108
114
|
|
|
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
|
|
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.
|
|
110
116
|
|
|
111
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.
|
|
112
118
|
|
|
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.
|
|
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.
|
|
114
120
|
|
|
115
|
-
|
|
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.
|
|
116
122
|
|
|
117
123
|
| Source | Contents |
|
|
118
124
|
|---|---|
|
|
@@ -121,10 +127,11 @@ Concurrency is in-process: a per-scan queue serializes read-modify-write operati
|
|
|
121
127
|
| `src/config.ts` | `Config` interface, `DEFAULT_CONFIG`, and the schema ranges enforced at startup. |
|
|
122
128
|
| `src/constants.ts` | Package and plugin names, version, route prefix, tool and skill name inventories. |
|
|
123
129
|
| `src/service.ts` | Scan lifecycle: target binding, drafts, validations, sealing, findings, exports, and comparisons. |
|
|
124
|
-
| `src/store.ts` | State directory resolution, scan directories, index
|
|
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. |
|
|
125
132
|
| `src/target.ts` | Target resolution, file inventory, content hashing, and language and size caps. |
|
|
126
133
|
| `src/git.ts` | Git revision, diff, and changed-file queries. |
|
|
127
|
-
| `src/tools.ts` | The
|
|
134
|
+
| `src/tools.ts` | The 31 `codex_security_*` tool definitions and their argument schemas. |
|
|
128
135
|
| `src/routes.ts` | `/plugins/codex-security` HTTP routes used by the workbench. |
|
|
129
136
|
| `src/contracts.ts` | Finding normalization and fingerprints, coverage, SARIF, and the policy gate. |
|
|
130
137
|
| `src/schema.ts` | AJV validation of sealed documents against `schemas/`. |
|
|
@@ -157,26 +164,26 @@ Concurrency is in-process: a per-scan queue serializes read-modify-write operati
|
|
|
157
164
|
<a id="model-experience"></a>
|
|
158
165
|
## Model Experience
|
|
159
166
|
|
|
160
|
-
Indirectly, through the
|
|
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.
|
|
161
168
|
|
|
162
169
|
#### KV Cache effect
|
|
163
170
|
|
|
164
|
-
Activating the layer adds
|
|
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.
|
|
165
172
|
|
|
166
173
|
<a id="known-limitations-and-deferred-work"></a>
|
|
167
174
|
## Known Limitations and Deferred Work
|
|
168
175
|
|
|
169
176
|
These limits define when the layer does not fit and what it needs from the profile around it.
|
|
170
177
|
|
|
171
|
-
- **
|
|
172
|
-
- **
|
|
173
|
-
- **Deep budgets
|
|
174
|
-
- **
|
|
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.
|
|
175
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.
|
|
176
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.
|
|
177
|
-
- **Native support for file exports** — the matching optional platform binary must be available for file export; if it is missing, export
|
|
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.
|
|
178
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.
|
|
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
|
|
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.
|
|
180
187
|
|
|
181
188
|
<a id="dev-note"></a>
|
|
182
189
|
### Dev Note
|
package/README.zh.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: "为 dsh profile 提供基于产物文件的安全审查能力:
|
|
2
|
+
description: "为 dsh profile 提供基于产物文件的安全审查能力:31 个 host 工具、16 个内置技能,以及一个把经过 schema 校验的扫描、发现、覆盖与导出封存在 profile 数据目录下的 Web 工作台。"
|
|
3
3
|
kind: "package-bundle"
|
|
4
4
|
---
|
|
5
5
|
|
|
@@ -9,7 +9,7 @@ kind: "package-bundle"
|
|
|
9
9
|
|
|
10
10
|
## 概要
|
|
11
11
|
|
|
12
|
-
`dsh-codex-security` 为 dsh profile 增加一套可复现的安全审查流程。它注册
|
|
12
|
+
`dsh-codex-security` 为 dsh profile 增加一套可复现的安全审查流程。它注册 31 个 `codex_security_*` host 工具、16 个内置技能,以及 Web GUI 中的 Codex Security 区块,用于查看扫描、发现、覆盖情况与导出结果。`add` 命令向 profile 插入一条 patch 行,`remove` 命令将其移除。本包记录并校验 agent 提交的审查内容,也可自动协调相互独立的 Deep worker;它不执行目标代码,完成的扫描会在 profile 数据目录下封存不可变产物。
|
|
13
13
|
|
|
14
14
|
## 目录
|
|
15
15
|
|
|
@@ -34,11 +34,11 @@ 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.
|
|
37
|
+
安装 GitHub 上的 0.1.8 版本,请运行 `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`。npm 仓库中的版本可能较旧。
|
|
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
|
|
|
41
|
-
安装或移除后重启 DSH,因为该条目在 profile 启动时才会被组合。启动时插件会输出 `codex-security: registered
|
|
41
|
+
安装或移除后重启 DSH,因为该条目在 profile 启动时才会被组合。启动时插件会输出 `codex-security: registered 16 skills` 与 `codex-security: ready (state dir will resolve on first scan)`,Web GUI 的 Settings 中会出现 Codex Security 入口;不运行 Web 客户端的 profile 仍然会获得工具与技能。
|
|
42
42
|
|
|
43
43
|
新 profile 初始没有任何扫描。第一次访问存储的请求——工作台的状态请求或 `codex_security_inspect_setup`——会解析状态目录并创建 `<stateDir>/repositories/`;只有在某个 start 工具运行之后才会出现扫描记录,插件本身不会审查任何内容。
|
|
44
44
|
|
|
@@ -48,10 +48,10 @@ dsh plugin --profile <name> remove @lornatang/dsh-codex-security
|
|
|
48
48
|
|
|
49
49
|
### 本包提供的内容
|
|
50
50
|
|
|
51
|
-
本包在组合后的 profile 中拥有三个表面:
|
|
51
|
+
本包在组合后的 profile 中拥有三个表面:31 个 host 工具、16 个技能,以及 Web GUI 中的一个工作台区块。[docs/TOOLS.md](docs/TOOLS.md) 记录了每个工具的参数与返回结构;[docs/CODEX-COMPATIBILITY.md](docs/CODEX-COMPATIBILITY.md) 说明与 Codex Security 的差异。
|
|
52
52
|
|
|
53
53
|
- **初始化与目标检查:** `codex_security_inspect_setup`、`codex_security_inspect_target`。
|
|
54
|
-
- **扫描生命周期:** `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`。
|
|
54
|
+
- **扫描生命周期:** `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
55
|
- **发现与候选:** `codex_security_record_discovery_candidates`、`codex_security_list_candidates`。
|
|
56
56
|
- **验证:** `codex_security_record_candidate_validations`、`codex_security_record_candidate_attack_paths`。
|
|
57
57
|
- **草稿与封存:** `codex_security_record_scan_draft`、`codex_security_complete_scan`、`codex_security_fail_scan`、`codex_security_cancel_scan`。
|
|
@@ -61,7 +61,7 @@ dsh plugin --profile <name> remove @lornatang/dsh-codex-security
|
|
|
61
61
|
- **查询与比较:** `codex_security_list_scans`、`codex_security_get_scan`、`codex_security_compare_scans`。
|
|
62
62
|
- **导出:** `codex_security_export_findings`。
|
|
63
63
|
|
|
64
|
-
|
|
64
|
+
技能目录新增 16 个条目,启动时分别从 `skills/<name>/SKILL.md` 加载,标记为 `source: bundled`,同时支持模型与用户调用:`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`、`validation`;每个工作流的文本位于 [skills/](skills/)。
|
|
65
65
|
|
|
66
66
|
Web GUI 新增一条 `settings.section` 行,id 为 `codex-security`,order 为 41,label 为 Codex Security,由本包的客户端部分(`src/client/index.tsx`,发布为 `lib/client.js`)通过 `@deepseek-ai/dsh-client-ui-slots` 与 `@deepseek-ai/dsh-client-ui-settings` 注册。面板显示版本、解析后的状态目录以及扫描与发现数量;它按状态与时间列出扫描,并打开所选扫描的 Overview、Findings、Coverage 与 Artifacts & exports 面板,其中包含 triage 选择器以及 SARIF、JSON、CSV、Markdown 下载链接。面板通过 `/plugins/codex-security` 下的 HTTP 路由读取同一个服务。
|
|
67
67
|
|
|
@@ -93,8 +93,14 @@ Web GUI 新增一条 `settings.section` 行,id 为 `codex-security`,order
|
|
|
93
93
|
| `failOnSeverity` | `high` | 策略门槛:`informational`、`low`、`medium`、`high`、`critical` 或 `off`。 |
|
|
94
94
|
| `allowExportOutsideWorkspace` | `false` | 允许导出到状态目录、进程工作目录与目标根路径之外。 |
|
|
95
95
|
| `maxScanAgeDays` | `30` | 工作台把扫描标记为超出策略窗口的天数,1–3650 天。 |
|
|
96
|
-
| `deepWorkers` | `4` |
|
|
97
|
-
| `deepMaxDiscoveryRuns` | `40` |
|
|
96
|
+
| `deepWorkers` | `4` | Deep 并发 worker 上限,1–32。 |
|
|
97
|
+
| `deepMaxDiscoveryRuns` | `40` | Deep 最大发现尝试次数,1–10000。 |
|
|
98
|
+
|
|
99
|
+
### 自动 Deep 扫描
|
|
100
|
+
|
|
101
|
+
调用 `codex_security_start_deep_scan` 启动独立 worker,并妥善保管返回的 `recoveryClaim`。使用 `codex_security_get_deep_scan_status` 查看进度;进程退出后可调用 `codex_security_resume_deep_scan` 恢复。原会话可不提供凭据,其他会话恢复或取消时必须提供。`workers`、`maxDiscoveryRuns`、`stopAfterNoNew` 和 `maxTimeMinutes` 限制并发、尝试次数、无新发现轮数与时间;中断的尝试仍消耗次数。目标目录对象在启动时绑定,文件内容在异步初始化阶段绑定。配置的 DSH 模型服务会接收源码,可能使用网络。
|
|
102
|
+
|
|
103
|
+
自动模式需要本地 DSH `spawn` provider、agent-preset registry、原生执行器和匹配平台的可选文件系统二进制。标准 Web profile 提供前三项;缺失时会安全失败。自动 Deep 支持仓库或目录快照,不支持 diff;可设置 `manual: true` 使用手动流程。worker 只能读取验证过的绑定源码分块并提交结构化结果。零发现结果要求至少一个完整 worker 收到所有文件;读取回执只能证明内容已送达。
|
|
98
104
|
|
|
99
105
|
-----
|
|
100
106
|
|
|
@@ -106,13 +112,13 @@ Web GUI 新增一条 `settings.section` 行,id 为 `codex-security`,order
|
|
|
106
112
|
|
|
107
113
|
这一层只有一条 patch 行:`insert` 一条 id 为 `codex-security`、包名为 `@lornatang/dsh-codex-security`、带三个配置值的条目。host 侧没有任何平台门控;清单中的 `dsh.client.platform: web` 只约束客户端 bundle,host 插件会在任何注入所需服务的 profile 中注册工具与技能。
|
|
108
114
|
|
|
109
|
-
Cordis 必须先注入 `tools` 与 `skills`,`apply` 才会运行。`apply` 使用解析后的配置与 profile patch 路径构建 `SecurityService`,然后分别注册
|
|
115
|
+
Cordis 必须先注入 `tools` 与 `skills`,`apply` 才会运行。`apply` 使用解析后的配置与 profile patch 路径构建 `SecurityService`,然后分别注册 31 个工具、从 `skills/*/SKILL.md` 发现并注册16 个内置技能、绑定可选的 HTTP 路由,每一项都在可释放的 effect 中执行。启动时不会创建状态目录;`ScanStore.init` 在第一次访问存储时创建它。
|
|
110
116
|
|
|
111
117
|
start 工具解析目标、绑定版本或 diff 事实、在限额内建立可审查文件清单、计算快照摘要,并在扫描目录下写入 `scan.json`。后续工具追加草稿、候选、验证、攻击路径、审查条目与已保存产物,每次扫描的队列会串行化这些修改。完成时重新解析目标、拒绝已变化的摘要、检查草稿与覆盖约定、构建 findings、coverage、SARIF 与 Markdown 文档,按内置 schema 校验 findings、coverage 与 manifest 文档,并写入封存该扫描的 manifest。
|
|
112
118
|
|
|
113
|
-
工作台通过 `/plugins/codex-security` 下的 `handleRequest` 访问同一个服务,路由在存在 `webServer` 或 `httpServer` 时注册。客户端部分单独编译为 CommonJS 并为 DSH 模块加载器封装;它注入 `settings.section`
|
|
119
|
+
工作台通过 `/plugins/codex-security` 下的 `handleRequest` 访问同一个服务,路由在存在 `webServer` 或 `httpServer` 时注册。客户端部分单独编译为 CommonJS 并为 DSH 模块加载器封装;它注入 `settings.section` 并请求这些路由。协调器通过配置的 DSH 模型服务派发隔离的静态审查 worker;模型服务可能使用网络,worker 不能执行目标代码。
|
|
114
120
|
|
|
115
|
-
|
|
121
|
+
SQLite 操作系统锁跨进程串行化协调器归属、扫描修改与索引更新;JSON 使用同目录原子替换。共享状态需要可信本地目录和可靠的 SQLite 文件锁;单个文件原子写入,但完整封存不是单个事务。
|
|
116
122
|
|
|
117
123
|
| 源码 | 内容 |
|
|
118
124
|
|---|---|
|
|
@@ -121,10 +127,11 @@ start 工具解析目标、绑定版本或 diff 事实、在限额内建立可
|
|
|
121
127
|
| `src/config.ts` | `Config` 接口、`DEFAULT_CONFIG`,以及启动时执行的 schema 范围。 |
|
|
122
128
|
| `src/constants.ts` | 包名与插件名、版本、路由前缀、工具与技能名称清单。 |
|
|
123
129
|
| `src/service.ts` | 扫描生命周期:目标绑定、草稿、验证、封存、发现、导出与比较。 |
|
|
124
|
-
| `src/store.ts` |
|
|
130
|
+
| `src/store.ts` | 状态目录解析、扫描目录、索引、原子 JSON 写入、封存文件集合。 |
|
|
131
|
+
| `src/deep-*.ts`、`src/secure-read.ts`、`src/state-lock.ts` | Deep 编排、隔离源码读取和跨进程锁。 |
|
|
125
132
|
| `src/target.ts` | 目标解析、文件清单、内容哈希,以及语言与大小上限。 |
|
|
126
133
|
| `src/git.ts` | Git 版本、diff 与变更文件查询。 |
|
|
127
|
-
| `src/tools.ts` |
|
|
134
|
+
| `src/tools.ts` | 31 个 `codex_security_*` 工具定义及其参数 schema。 |
|
|
128
135
|
| `src/routes.ts` | 工作台使用的 `/plugins/codex-security` HTTP 路由。 |
|
|
129
136
|
| `src/contracts.ts` | 发现规范化与指纹、coverage、SARIF 以及策略门槛。 |
|
|
130
137
|
| `src/schema.ts` | 按 `schemas/` 对封存文档执行 AJV 校验。 |
|
|
@@ -157,24 +164,24 @@ start 工具解析目标、绑定版本或 diff 事实、在限额内建立可
|
|
|
157
164
|
<a id="model-experience"></a>
|
|
158
165
|
## 模型体验
|
|
159
166
|
|
|
160
|
-
间接地,通过注册的
|
|
167
|
+
间接地,通过注册的 31 个工具 schema 与16 个内置技能描述:它们的名称、描述与参数 schema 进入模型的工具与技能目录,而扫描状态只有在 agent 调用工具后以 JSON 结果的形式到达模型。
|
|
161
168
|
|
|
162
169
|
#### KV Cache 影响
|
|
163
170
|
|
|
164
|
-
启用这一层会向 host 为会话构建的 prompt 前缀中加入
|
|
171
|
+
启用这一层会向 host 为会话构建的 prompt 前缀中加入 31 个工具定义与16 个技能目录条目,移除时则删除同样的文本。会话期间目录保持稳定,因此新增的 token 属于缓存的 prefix,不会逐轮增长;开始、更新与完成扫描只是在 prefix 之后追加普通的工具结果与 assistant 消息。自动 worker 还会收到审查提示和其请求的已验证源码分块。
|
|
165
172
|
|
|
166
173
|
<a id="known-limitations-and-deferred-work"></a>
|
|
167
174
|
## 已知限制与后续工作
|
|
168
175
|
|
|
169
176
|
这些限制说明这一层在什么情况下不适用,以及它对周围 profile 的要求。
|
|
170
177
|
|
|
171
|
-
-
|
|
172
|
-
-
|
|
173
|
-
- **
|
|
174
|
-
-
|
|
178
|
+
- **模型审查** — host 存储并校验 agent 提交的内容,无法证明模型理解了每个文件,也无法保证覆盖穷尽。
|
|
179
|
+
- **静态审查** — 受限 worker 不构建或执行目标代码;配置的模型服务可能使用网络,运行期弱点不在静态证据范围内。
|
|
180
|
+
- **Deep 预算** — 自动模式限制 worker、尝试次数、无新发现轮数与时间,但不设 token 或金额上限;手动模式的预算仅供参考。
|
|
181
|
+
- **本地状态** — 跨进程协调需要可信本地目录和可靠的 SQLite 文件锁;失败的中途封存可能留下中间文件。
|
|
175
182
|
- **封存是单向的** — agent 产物只能在扫描运行期间写入,`codex_security_save_artifact` 会拒绝封存文件与内部路径;triage 是完成后的唯一修改途径,且不会改动已封存文档。
|
|
176
183
|
- **默认限制导出范围** — 写入状态目录、进程工作目录与目标根路径之外需要 `allowExportOutsideWorkspace: true`;导出到 `repositories/` 下的扫描存储始终被拒绝。
|
|
177
|
-
- **文件导出需要原生支持** —
|
|
184
|
+
- **文件导出需要原生支持** — 文件导出需要与平台匹配的可选二进制包;缺少时文件导出与自动 worker 源码读取会安全失败,手动扫描与内存导出仍可用。该二进制包没有依赖安装脚本。
|
|
178
185
|
- **清单上限决定证据范围** — `maxFiles` 与 `maxFileBytes` 限制可审查清单,不可读文件会变成警告,快照摘要只覆盖清单内的内容,因此超出上限的文件不在证据范围内。
|
|
179
186
|
- **比较不能证明修复** — `codex_security_compare_scans` 要求目标、模式与范围兼容、覆盖完整且清单未被截断的已完成扫描,并且只做指纹分类;指纹缺失不等于已验证修复。
|
|
180
187
|
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Architecture
|
|
2
2
|
|
|
3
|
-
The package is a DSH host plugin with a separately compiled web client. Its scan service records
|
|
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
4
|
|
|
5
5
|
## Repository layout
|
|
6
6
|
|
|
@@ -11,10 +11,12 @@ src/index.ts Host entry and bundled-skill registration
|
|
|
11
11
|
src/config.ts, constants.ts Configuration and public names
|
|
12
12
|
src/target.ts, git.ts Target binding, inventory and Git queries
|
|
13
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
|
|
14
16
|
src/contracts.ts, schema.ts Artifact construction and schema validation
|
|
15
17
|
src/tools.ts, routes.ts Agent tools and HTTP routes
|
|
16
18
|
src/client/index.tsx Workbench settings section
|
|
17
|
-
skills/
|
|
19
|
+
skills/ Sixteen agent workflows
|
|
18
20
|
schemas/ JSON Schema contracts
|
|
19
21
|
references/ Adapted reference material
|
|
20
22
|
examples/ Illustrative artifacts
|
|
@@ -28,7 +30,7 @@ The host build emits ESM and declarations to `lib/`; the client build emits Comm
|
|
|
28
30
|
|
|
29
31
|
## Host lifecycle
|
|
30
32
|
|
|
31
|
-
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,
|
|
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.
|
|
32
34
|
|
|
33
35
|
## Target binding
|
|
34
36
|
|
|
@@ -44,10 +46,14 @@ A scan starts as `running` and may become `completed`, `failed` or `canceled`. C
|
|
|
44
46
|
|
|
45
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.
|
|
46
48
|
|
|
47
|
-
Comparison requires completed scans with compatible target, mode and scope, complete coverage and non-truncated inventories. It
|
|
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.
|
|
48
50
|
|
|
49
51
|
## Concurrency and limits
|
|
50
52
|
|
|
51
|
-
A per-scan
|
|
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.
|
|
52
54
|
|
|
53
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
|
@@ -12,6 +12,7 @@ A scan is stored at `<stateDir>/repositories/<repoKey>/scans/<scanId>/`. IDs are
|
|
|
12
12
|
| `report.md` | Human-readable static review report | Yes |
|
|
13
13
|
| `sarif.json` | SARIF 2.1.0 representation | Yes |
|
|
14
14
|
| `threat-model.md` | Optional threat model | When present |
|
|
15
|
+
| `threatmodel.md` | Codex-compatible threat-model projection | When present |
|
|
15
16
|
| Agent-saved artifacts | Writeups and other supporting files | Yes |
|
|
16
17
|
| `checkpoints/scan-draft.json` | Most recent draft checkpoint | No |
|
|
17
18
|
| `candidates.json`, `validations.json`, `attack-paths.json` | Candidate ledger | No |
|
|
@@ -25,11 +26,13 @@ Agent-saved files are scan-relative. Common paths are `findings/<slug>/<slug>.md
|
|
|
25
26
|
|
|
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 `[]`.
|
|
27
28
|
|
|
28
|
-
The primary fingerprint is `codex-security/v1:sha256:` followed by the SHA-256 of the
|
|
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.
|
|
29
32
|
|
|
30
33
|
## Coverage
|
|
31
34
|
|
|
32
|
-
`coverage.json` records the scan mode, 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`.
|
|
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.
|
|
33
36
|
|
|
34
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.
|
|
35
38
|
|
|
@@ -41,6 +44,6 @@ The snapshot identifies the bound revision and diff list and, for directory and
|
|
|
41
44
|
|
|
42
45
|
## Drafts, comparison and exports
|
|
43
46
|
|
|
44
|
-
`record_scan_draft` replaces the previous checkpoint. 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
|
|
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.
|
|
45
48
|
|
|
46
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.
|
|
@@ -0,0 +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.
|
package/docs/SPEC.md
CHANGED
|
@@ -5,10 +5,10 @@ The project provides an independent DSH implementation of a skill-driven static
|
|
|
5
5
|
## Product surface
|
|
6
6
|
|
|
7
7
|
- Package: `@lornatang/dsh-codex-security`; plugin and patch row: `codex-security`.
|
|
8
|
-
- Host:
|
|
8
|
+
- Host: 31 `codex_security_*` tools and 16 bundled skills. `tools` and `skills` are required Cordis services.
|
|
9
9
|
- Client: one **Codex Security** settings section backed by local HTTP routes.
|
|
10
10
|
- Scan modes: `standard`, `prompt-only`, `deep`. `codex_security_start_scan` uses the configured default; named start tools select their mode explicitly.
|
|
11
|
-
- Deep
|
|
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
12
|
|
|
13
13
|
## Configuration
|
|
14
14
|
|
|
@@ -21,8 +21,8 @@ The project provides an independent DSH implementation of a skill-driven static
|
|
|
21
21
|
| `failOnSeverity` | `high` | Policy threshold or `off`. |
|
|
22
22
|
| `allowExportOutsideWorkspace` | `false` | Permit explicitly requested exports outside permitted roots. |
|
|
23
23
|
| `maxScanAgeDays` | `30` | Workbench age warning; no automatic deletion. |
|
|
24
|
-
| `deepWorkers` | `4` | Default
|
|
25
|
-
| `deepMaxDiscoveryRuns` | `40` | Default
|
|
24
|
+
| `deepWorkers` | `4` | Default concurrent worker limit. |
|
|
25
|
+
| `deepMaxDiscoveryRuns` | `40` | Default maximum discovery attempts. |
|
|
26
26
|
|
|
27
27
|
## Lifecycle and storage
|
|
28
28
|
|
|
@@ -32,7 +32,7 @@ Completion requires a draft marked complete, at least one coverage surface, cand
|
|
|
32
32
|
|
|
33
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
34
|
|
|
35
|
-
State is local.
|
|
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
36
|
|
|
37
37
|
## Workbench and routes
|
|
38
38
|
|
|
@@ -40,4 +40,4 @@ The host registers `/plugins/codex-security` routes for status, configuration, s
|
|
|
40
40
|
|
|
41
41
|
## Security and scope
|
|
42
42
|
|
|
43
|
-
The host uses read-only Git queries and does not build or execute the reviewed target. 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.
|
|
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.
|