@lornatang/dsh-codex-security 0.1.11 → 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 (42) hide show
  1. package/CHANGELOG.md +13 -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 +103 -14
  15. package/lib/deep-worker.js +4 -1
  16. package/lib/git.js +44 -8
  17. package/lib/service.js +91 -52
  18. package/lib/store.js +93 -32
  19. package/lib/target.js +71 -13
  20. package/lib/tools.js +47 -1
  21. package/lib/types/constants.d.ts +1 -1
  22. package/lib/types/deep-coordinator.d.ts +4 -0
  23. package/lib/types/git.d.ts +4 -0
  24. package/lib/types/index.d.ts +1 -1
  25. package/lib/types/service.d.ts +5 -3
  26. package/lib/types/store.d.ts +11 -2
  27. package/lib/types/target.d.ts +15 -1
  28. package/lib/types/util.d.ts +1 -0
  29. package/lib/util.js +18 -15
  30. package/package.json +1 -1
  31. package/schemas/coverage.schema.json +136 -136
  32. package/skills/README.md +122 -122
  33. package/skills/assess-patch-risk/SKILL.md +10 -10
  34. package/skills/attack-path-analysis/SKILL.md +10 -10
  35. package/skills/deep-security-scan/SKILL.md +15 -15
  36. package/skills/define-security-policy/SKILL.md +10 -10
  37. package/skills/finding-discovery/SKILL.md +10 -10
  38. package/skills/fix-finding/SKILL.md +14 -14
  39. package/skills/propose-security-hardening/SKILL.md +10 -10
  40. package/skills/track-findings/SKILL.md +12 -12
  41. package/skills/validation/SKILL.md +10 -10
  42. package/skills/verify-fix/SKILL.md +14 -14
package/lib/tools.js CHANGED
@@ -13,6 +13,52 @@ const FORMAT_ENUM = ENUM('sarif', 'json', 'csv', 'markdown');
13
13
  function render(_args, value) {
14
14
  return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
15
15
  }
16
+ /**
17
+ * DSH rejects values containing undefined even though JSON.stringify drops them.
18
+ * A full JSON round-trip on every tool result allocates a second copy of large
19
+ * responses; walk the value instead and keep it when nothing needs normalizing.
20
+ */
21
+ function normalizeToolResult(value) {
22
+ return normalizeValue(value, new Set());
23
+ }
24
+ function normalizeValue(value, seen) {
25
+ if (value === undefined || typeof value === 'function' || typeof value === 'symbol')
26
+ return undefined;
27
+ if (typeof value === 'number')
28
+ return Number.isFinite(value) ? value : null;
29
+ if (typeof value !== 'object' || value === null)
30
+ return value;
31
+ if (seen.has(value))
32
+ throw new TypeError('codex-security: tool result contains a circular structure');
33
+ if (Array.isArray(value)) {
34
+ seen.add(value);
35
+ let changed = false;
36
+ const normalized = value.map((item) => {
37
+ const next = normalizeValue(item, seen);
38
+ const result = next === undefined ? null : next;
39
+ if (result !== item)
40
+ changed = true;
41
+ return result;
42
+ });
43
+ seen.delete(value);
44
+ return changed ? normalized : value;
45
+ }
46
+ seen.add(value);
47
+ let changed = false;
48
+ const normalized = {};
49
+ for (const [key, item] of Object.entries(value)) {
50
+ const next = normalizeValue(item, seen);
51
+ if (next === undefined) {
52
+ changed = true;
53
+ continue;
54
+ }
55
+ if (next !== item)
56
+ changed = true;
57
+ normalized[key] = next;
58
+ }
59
+ seen.delete(value);
60
+ return changed ? normalized : value;
61
+ }
16
62
  function tool(name, description, properties, required, run, timeoutMs = 180000) {
17
63
  const parameters = { type: 'object', properties, ...(required.length > 0 ? { required } : {}), additionalProperties: false };
18
64
  const validate = compileToolArguments(parameters);
@@ -24,7 +70,7 @@ function tool(name, description, properties, required, run, timeoutMs = 180000)
24
70
  timeoutMs,
25
71
  // DSH rejects values containing undefined even though JSON.stringify drops them.
26
72
  // Normalize the whole response, including nested optional fields, at the boundary.
27
- execute: async (args, exec) => { validate(args); return JSON.parse(JSON.stringify(await run(args, exec))); },
73
+ execute: async (args, exec) => { validate(args); return normalizeToolResult(await run(args, exec)); },
28
74
  };
29
75
  }
30
76
  const SCAN_ID = { type: 'string', description: 'Scan id returned by a codex_security_start_*_scan tool, e.g. cs_<24 hex chars>.' };
@@ -1,6 +1,6 @@
1
1
  export declare const PACKAGE_NAME = "@lornatang/dsh-codex-security";
2
2
  export declare const PLUGIN_NAME = "codex-security";
3
- export declare const VERSION = "0.1.11";
3
+ export declare const VERSION = "0.1.13";
4
4
  export declare const ROUTE_PREFIX = "/plugins/codex-security";
5
5
  export declare const PRODUCER: {
6
6
  name: string;
@@ -42,8 +42,12 @@ export declare class DeepCoordinator {
42
42
  private lockPath;
43
43
  private transitionPath;
44
44
  private cancelPath;
45
+ private runSidecarDir;
46
+ private runSidecarPath;
47
+ private readonly dirtyPayloads;
45
48
  private save;
46
49
  private read;
50
+ private restoreRunPayloads;
47
51
  private authorize;
48
52
  start(args: Json, actor: DeepActor): Promise<Json>;
49
53
  resume(args: Json, actor: DeepActor): Promise<Json>;
@@ -23,7 +23,11 @@ export interface ChangedFile {
23
23
  }
24
24
  export declare function changedFiles(root: string, options: {
25
25
  base?: string;
26
+ head?: string;
26
27
  staged?: boolean;
27
28
  workingTree?: boolean;
29
+ signal?: AbortSignal;
28
30
  }): Promise<ChangedFile[]>;
31
+ /** Read a bounded prefix of a regular file from the exact commit. */
32
+ export declare function revisionFilePrefix(root: string, revision: string, path: string, limit: number): Promise<Buffer | undefined>;
29
33
  export declare function fileDigest(path: string, signal?: AbortSignal): Promise<string | undefined>;
@@ -6,7 +6,7 @@ import type { PluginContext } from './types.js';
6
6
  export declare const name = "codex-security";
7
7
  export declare const inject: string[];
8
8
  export { Config };
9
- export declare const version = "0.1.11";
9
+ export declare const version = "0.1.13";
10
10
  export { SecurityService };
11
11
  export type { ConfigType };
12
12
  export declare function loadBundledSkills(packageRoot: string): SkillRegistration[];
@@ -4,6 +4,10 @@ import { ScanStore } from './store.js';
4
4
  import type { WorkerSnapshot } from './deep-worker.js';
5
5
  export declare const FORMATS: readonly ["sarif", "json", "csv", "markdown"];
6
6
  export type ExportFormat = (typeof FORMATS)[number];
7
+ interface SealOptions {
8
+ signal?: AbortSignal;
9
+ withPublication?: (publish: () => Promise<void>) => Promise<void>;
10
+ }
7
11
  type Json = Record<string, unknown>;
8
12
  export interface SecurityServiceOptions {
9
13
  config?: Partial<Config>;
@@ -60,9 +64,7 @@ export declare class SecurityService {
60
64
  saveArtifact(args: Json): Promise<Json>;
61
65
  private saveArtifactUnlocked;
62
66
  readArtifact(args: Json): Promise<Json>;
63
- completeScan(args: Json, options?: {
64
- signal?: AbortSignal;
65
- }): Promise<Json>;
67
+ completeScan(args: Json, options?: SealOptions): Promise<Json>;
66
68
  private completeScanUnlocked;
67
69
  failScan(args: Json): Promise<Json>;
68
70
  private failScanUnlocked;
@@ -27,11 +27,17 @@ export declare function summarize(record: ScanRecord): ScanSummary;
27
27
  export declare class ScanStore {
28
28
  readonly stateDir: string;
29
29
  private queue;
30
+ private indexCache?;
31
+ private indexStamp?;
30
32
  constructor(stateDir: string);
31
33
  private get indexPath();
34
+ private get indexLockPath();
32
35
  scanDir(record: Pick<ScanRecord, 'repoKey' | 'scanId'>): string;
33
36
  init(): Promise<void>;
34
37
  private serialize;
38
+ /** Cheap identity of index.json so a changed on-disk index invalidates the cache. */
39
+ private indexFileStamp;
40
+ private readIndex;
35
41
  loadIndex(): Promise<ScanIndex>;
36
42
  private rebuildIndex;
37
43
  saveIndex(index: ScanIndex): Promise<void>;
@@ -43,7 +49,10 @@ export declare class ScanStore {
43
49
  record: ScanRecord;
44
50
  dir: string;
45
51
  } | undefined>;
46
- update(scanId: string, mutate: (record: ScanRecord) => void): Promise<ScanRecord>;
52
+ update(scanId: string, mutate: (record: ScanRecord) => void, options?: {
53
+ signal?: AbortSignal;
54
+ publish?: (commit: () => Promise<void>) => Promise<void>;
55
+ }): Promise<ScanRecord>;
47
56
  writeScanFile(scanId: string, name: string, value: unknown): Promise<string>;
48
57
  readScanFile<T>(scanId: string, name: string): Promise<T | undefined>;
49
58
  list(): Promise<ScanSummary[]>;
@@ -59,7 +68,7 @@ export declare class ScanStore {
59
68
  bytes: number;
60
69
  truncated: boolean;
61
70
  }>;
62
- listArtifacts(scanId: string): Promise<{
71
+ listArtifacts(scanId: string, knownDir?: string): Promise<{
63
72
  path: string;
64
73
  bytes: number;
65
74
  }[]>;
@@ -30,8 +30,22 @@ export interface DiffSnapshot {
30
30
  }
31
31
  export declare function resolveDiff(rootPath: string, options: {
32
32
  diffTarget?: string;
33
+ head?: string;
33
34
  staged?: boolean;
34
35
  workingTree?: boolean;
36
+ signal?: AbortSignal;
35
37
  }): Promise<DiffSnapshot>;
38
+ type EvidenceSource = string | Pick<TargetInfo, 'rootPath' | 'kind' | 'workingTree' | 'revision' | 'headRevision'>;
36
39
  /** Read one source line for anchor derivation without trusting it as instructions. */
37
- export declare function readEvidenceLine(rootPath: string, path: string, line: number, maxBytes: number): Promise<string | undefined>;
40
+ export declare function readEvidenceLine(source: EvidenceSource, path: string, line: number, maxBytes: number): Promise<string | undefined>;
41
+ /**
42
+ * Read many evidence lines with one hardened open per source file. The old
43
+ * per-line reader repeated the lstat/open/realpath verification and re-read the
44
+ * file prefix for every requested line, so a draft citing several lines of one
45
+ * file paid that cost repeatedly.
46
+ */
47
+ export declare function readEvidenceLines(source: EvidenceSource, requests: {
48
+ path: string;
49
+ line: number;
50
+ }[], maxBytes: number): Promise<Map<string, string>>;
51
+ export {};
@@ -5,6 +5,7 @@ export declare function nowIso(): string;
5
5
  export declare function newId(prefix: string, hexChars?: number): string;
6
6
  export declare function ensureDir(path: string): Promise<void>;
7
7
  export declare function writeFileAtomic(path: string, data: string | Uint8Array): Promise<void>;
8
+ export declare function renameFileAtomic(from: string, to: string): Promise<void>;
8
9
  /** Resolve symlinked ancestors even when the final path does not yet exist. */
9
10
  export declare function canonicalProspectivePath(path: string): Promise<string>;
10
11
  export declare function writeJsonAtomic(path: string, value: unknown): Promise<void>;
package/lib/util.js CHANGED
@@ -29,27 +29,30 @@ export async function writeFileAtomic(path, data) {
29
29
  finally {
30
30
  await handle.close();
31
31
  }
32
- const deadline = Date.now() + 2000;
33
- let pause = 10;
34
- for (;;) {
35
- try {
36
- await rename(tmp, path);
37
- break;
38
- }
39
- catch (error) {
40
- const code = error.code;
41
- if (process.platform !== 'win32' || !['EPERM', 'EACCES', 'EBUSY'].includes(code ?? '') || Date.now() >= deadline)
42
- throw error;
43
- await delay(pause);
44
- pause = Math.min(100, pause * 2);
45
- }
46
- }
32
+ await renameFileAtomic(tmp, path);
47
33
  }
48
34
  catch (error) {
49
35
  await rm(tmp, { force: true }).catch(() => undefined);
50
36
  throw error;
51
37
  }
52
38
  }
39
+ export async function renameFileAtomic(from, to) {
40
+ const deadline = Date.now() + 2000;
41
+ let pause = 10;
42
+ for (;;) {
43
+ try {
44
+ await rename(from, to);
45
+ return;
46
+ }
47
+ catch (error) {
48
+ const code = error.code;
49
+ if (process.platform !== 'win32' || !['EPERM', 'EACCES', 'EBUSY'].includes(code ?? '') || Date.now() >= deadline)
50
+ throw error;
51
+ await delay(pause);
52
+ pause = Math.min(100, pause * 2);
53
+ }
54
+ }
55
+ }
53
56
  /** Resolve symlinked ancestors even when the final path does not yet exist. */
54
57
  export async function canonicalProspectivePath(path) {
55
58
  let current = resolve(path);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lornatang/dsh-codex-security",
3
- "version": "0.1.11",
3
+ "version": "0.1.13",
4
4
  "description": "Agent-native security review workbench for DeepSeek Harness, modeled on OpenAI codex-security: sealed scans, findings contract, deep-scan orchestration and SARIF/JSON export.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -1,136 +1,136 @@
1
- {
2
- "$id": "https://openai.com/codex-security/schemas/coverage.schema.json",
3
- "title": "Codex Security scan coverage",
4
- "$schema": "https://json-schema.org/draft/2020-12/schema",
5
- "type": "object",
6
- "properties": {
7
- "documentType": { "const": "codex-security.coverage" },
8
- "schemaVersion": { "const": "1.0" },
9
- "scanId": { "type": "string", "minLength": 1 },
10
- "completeness": { "enum": ["complete", "partial", "unknown"] },
11
- "mode": {
12
- "enum": [
13
- "repository",
14
- "scoped_path",
15
- "diff",
16
- "commit",
17
- "branch_diff",
18
- "working_tree",
19
- "deep_repository"
20
- ]
21
- },
22
- "inventoryStrategy": {
23
- "enum": ["repository", "scoped_path", "diff", "directory", "custom"]
24
- },
25
- "includePaths": { "type": "array", "items": { "type": "string" } },
26
- "excludePaths": { "type": "array", "items": { "type": "string" } },
27
- "surfaces": {
28
- "type": "array",
29
- "items": {
30
- "type": "object",
31
- "properties": {
32
- "id": { "type": "string", "minLength": 1 },
33
- "label": { "type": "string", "minLength": 1 },
34
- "disposition": {
35
- "enum": [
36
- "reported",
37
- "no_issue_found",
38
- "rejected",
39
- "not_applicable",
40
- "needs_follow_up"
41
- ]
42
- },
43
- "receiptRefs": {
44
- "type": "array",
45
- "items": {
46
- "type": "string",
47
- "minLength": 1,
48
- "pattern": "^(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\)artifacts/.+$"
49
- }
50
- },
51
- "riskArea": { "type": "string", "minLength": 1 },
52
- "notes": { "type": "string", "minLength": 1 }
53
- },
54
- "required": ["id", "label", "disposition", "receiptRefs"]
55
- }
56
- },
57
- "explicitExclusions": {
58
- "type": "array",
59
- "items": {
60
- "type": "object",
61
- "properties": {
62
- "pattern": { "type": "string", "minLength": 1 },
63
- "reason": { "type": "string", "minLength": 1 }
64
- },
65
- "required": ["pattern", "reason"]
66
- }
67
- },
68
- "deferred": {
69
- "type": "array",
70
- "items": {
71
- "type": "object",
72
- "properties": {
73
- "id": { "type": "string", "minLength": 1 },
74
- "reason": { "type": "string", "minLength": 1 },
75
- "paths": {
76
- "type": "array",
77
- "items": {
78
- "type": "string",
79
- "minLength": 1,
80
- "oneOf": [
81
- {},
82
- {
83
- "type": "string",
84
- "$comment": "invalidSealedDeferredPath",
85
- "pattern": "^(?:/|[A-Za-z]:)|(?:^|/)\\.\\.(?:/|$)|[\\\\\\x00-\\x1f]|[\\ud800-\\udbff](?![\\udc00-\\udfff])|(?:^|[^\\ud800-\\udbff])[\\udc00-\\udfff]"
86
- }
87
- ]
88
- }
89
- },
90
- "surfaceIds": {
91
- "type": "array",
92
- "items": { "type": "string", "minLength": 1 }
93
- }
94
- },
95
- "required": ["id", "reason"]
96
- }
97
- },
98
- "resolvedDeferred": {
99
- "type": "array",
100
- "items": {
101
- "type": "object",
102
- "properties": {
103
- "id": { "type": "string", "minLength": 1 },
104
- "reason": { "type": "string", "minLength": 1 }
105
- },
106
- "required": ["id", "reason"],
107
- "additionalProperties": false
108
- },
109
- "description": "Completed generic review tasks, with their saved IDs and completion reasons."
110
- },
111
- "openQuestions": {
112
- "type": "array",
113
- "items": {
114
- "type": "object",
115
- "properties": {
116
- "question": { "type": "string", "minLength": 1 },
117
- "followUpPrompt": { "type": "string", "minLength": 1 }
118
- },
119
- "required": ["question"]
120
- }
121
- }
122
- },
123
- "required": [
124
- "documentType",
125
- "schemaVersion",
126
- "scanId",
127
- "mode",
128
- "completeness",
129
- "inventoryStrategy",
130
- "includePaths",
131
- "excludePaths",
132
- "surfaces",
133
- "explicitExclusions",
134
- "deferred"
135
- ]
136
- }
1
+ {
2
+ "$id": "https://openai.com/codex-security/schemas/coverage.schema.json",
3
+ "title": "Codex Security scan coverage",
4
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
5
+ "type": "object",
6
+ "properties": {
7
+ "documentType": { "const": "codex-security.coverage" },
8
+ "schemaVersion": { "const": "1.0" },
9
+ "scanId": { "type": "string", "minLength": 1 },
10
+ "completeness": { "enum": ["complete", "partial", "unknown"] },
11
+ "mode": {
12
+ "enum": [
13
+ "repository",
14
+ "scoped_path",
15
+ "diff",
16
+ "commit",
17
+ "branch_diff",
18
+ "working_tree",
19
+ "deep_repository"
20
+ ]
21
+ },
22
+ "inventoryStrategy": {
23
+ "enum": ["repository", "scoped_path", "diff", "directory", "custom"]
24
+ },
25
+ "includePaths": { "type": "array", "items": { "type": "string" } },
26
+ "excludePaths": { "type": "array", "items": { "type": "string" } },
27
+ "surfaces": {
28
+ "type": "array",
29
+ "items": {
30
+ "type": "object",
31
+ "properties": {
32
+ "id": { "type": "string", "minLength": 1 },
33
+ "label": { "type": "string", "minLength": 1 },
34
+ "disposition": {
35
+ "enum": [
36
+ "reported",
37
+ "no_issue_found",
38
+ "rejected",
39
+ "not_applicable",
40
+ "needs_follow_up"
41
+ ]
42
+ },
43
+ "receiptRefs": {
44
+ "type": "array",
45
+ "items": {
46
+ "type": "string",
47
+ "minLength": 1,
48
+ "pattern": "^(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\)artifacts/.+$"
49
+ }
50
+ },
51
+ "riskArea": { "type": "string", "minLength": 1 },
52
+ "notes": { "type": "string", "minLength": 1 }
53
+ },
54
+ "required": ["id", "label", "disposition", "receiptRefs"]
55
+ }
56
+ },
57
+ "explicitExclusions": {
58
+ "type": "array",
59
+ "items": {
60
+ "type": "object",
61
+ "properties": {
62
+ "pattern": { "type": "string", "minLength": 1 },
63
+ "reason": { "type": "string", "minLength": 1 }
64
+ },
65
+ "required": ["pattern", "reason"]
66
+ }
67
+ },
68
+ "deferred": {
69
+ "type": "array",
70
+ "items": {
71
+ "type": "object",
72
+ "properties": {
73
+ "id": { "type": "string", "minLength": 1 },
74
+ "reason": { "type": "string", "minLength": 1 },
75
+ "paths": {
76
+ "type": "array",
77
+ "items": {
78
+ "type": "string",
79
+ "minLength": 1,
80
+ "oneOf": [
81
+ {},
82
+ {
83
+ "type": "string",
84
+ "$comment": "invalidSealedDeferredPath",
85
+ "pattern": "^(?:/|[A-Za-z]:)|(?:^|/)\\.\\.(?:/|$)|[\\\\\\x00-\\x1f]|[\\ud800-\\udbff](?![\\udc00-\\udfff])|(?:^|[^\\ud800-\\udbff])[\\udc00-\\udfff]"
86
+ }
87
+ ]
88
+ }
89
+ },
90
+ "surfaceIds": {
91
+ "type": "array",
92
+ "items": { "type": "string", "minLength": 1 }
93
+ }
94
+ },
95
+ "required": ["id", "reason"]
96
+ }
97
+ },
98
+ "resolvedDeferred": {
99
+ "type": "array",
100
+ "items": {
101
+ "type": "object",
102
+ "properties": {
103
+ "id": { "type": "string", "minLength": 1 },
104
+ "reason": { "type": "string", "minLength": 1 }
105
+ },
106
+ "required": ["id", "reason"],
107
+ "additionalProperties": false
108
+ },
109
+ "description": "Completed generic review tasks, with their saved IDs and completion reasons."
110
+ },
111
+ "openQuestions": {
112
+ "type": "array",
113
+ "items": {
114
+ "type": "object",
115
+ "properties": {
116
+ "question": { "type": "string", "minLength": 1 },
117
+ "followUpPrompt": { "type": "string", "minLength": 1 }
118
+ },
119
+ "required": ["question"]
120
+ }
121
+ }
122
+ },
123
+ "required": [
124
+ "documentType",
125
+ "schemaVersion",
126
+ "scanId",
127
+ "mode",
128
+ "completeness",
129
+ "inventoryStrategy",
130
+ "includePaths",
131
+ "excludePaths",
132
+ "surfaces",
133
+ "explicitExclusions",
134
+ "deferred"
135
+ ]
136
+ }