@lornatang/dsh-codex-security 0.1.9 → 0.1.10
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 +15 -0
- package/README.md +196 -196
- package/README.zh.md +196 -196
- package/docs/ARCHITECTURE.md +59 -59
- package/docs/ARTIFACTS.md +49 -49
- package/docs/CODEX-COMPATIBILITY.md +17 -17
- package/docs/SPEC.md +43 -43
- package/docs/TOOLS.md +364 -364
- package/docs/VALIDATION.md +33 -33
- package/docs/superpowers/plans/2026-11-16-deep-scan.md +71 -71
- package/docs/superpowers/specs/2026-11-16-deep-scan-design.md +31 -31
- package/lib/constants.js +1 -1
- package/lib/contracts.js +12 -2
- package/lib/deep-coordinator.js +23 -12
- package/lib/deep-worker.js +26 -2
- package/lib/routes.js +29 -1
- package/lib/service.js +45 -26
- package/lib/store.js +17 -3
- package/lib/target.js +30 -7
- package/lib/tools.js +4 -12
- package/lib/types/constants.d.ts +1 -1
- package/lib/types/deep-coordinator.d.ts +3 -1
- package/lib/types/deep-worker.d.ts +4 -0
- package/lib/types/index.d.ts +1 -1
- package/package.json +2 -2
- package/schemas/coverage.schema.json +136 -136
- package/skills/README.md +122 -122
- package/skills/assess-patch-risk/SKILL.md +10 -10
- package/skills/attack-path-analysis/SKILL.md +10 -10
- package/skills/deep-security-scan/SKILL.md +15 -15
- package/skills/define-security-policy/SKILL.md +10 -10
- package/skills/finding-discovery/SKILL.md +10 -10
- package/skills/fix-finding/SKILL.md +14 -14
- package/skills/propose-security-hardening/SKILL.md +10 -10
- package/skills/track-findings/SKILL.md +12 -12
- package/skills/validation/SKILL.md +10 -10
- package/skills/verify-fix/SKILL.md +14 -14
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.
|