@openai/codex-security 0.1.4 → 0.1.6
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/README.md +127 -13
- package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
- package/_bundled_plugin/.mcp.json +8 -1
- package/_bundled_plugin/examples/completed-scan/findings.json +6 -0
- package/_bundled_plugin/examples/completed-scan/scan-manifest.json +1 -1
- package/_bundled_plugin/mcp/mcp-app.html.br +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
- package/_bundled_plugin/preflight/capability-profiles.toml +0 -57
- package/_bundled_plugin/references/config-preflight.md +1 -1
- package/_bundled_plugin/references/final-report.md +15 -7
- package/_bundled_plugin/references/finding-detail-fields.md +10 -2
- package/_bundled_plugin/references/scan-artifacts.md +11 -9
- package/_bundled_plugin/references/scan-contract.md +3 -1
- package/_bundled_plugin/schemas/definitions/artifact-common.schema.json +42 -0
- package/_bundled_plugin/schemas/definitions/discovery-candidate.schema.json +100 -0
- package/_bundled_plugin/schemas/tools/candidate-attack-paths.schema.json +181 -0
- package/_bundled_plugin/schemas/tools/candidate-validations.schema.json +166 -0
- package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +120 -0
- package/_bundled_plugin/schemas/tools/discovery-candidates.schema.json +83 -0
- package/_bundled_plugin/schemas/tools/review-items.schema.json +80 -0
- package/_bundled_plugin/schemas/tools/scan-draft.schema.json +572 -0
- package/_bundled_plugin/schemas/tools/worker-threat-model.schema.json +18 -0
- package/_bundled_plugin/scripts/deep_scan_config.py +11 -3
- package/_bundled_plugin/scripts/deep_scan_workbench.py +153 -133
- package/_bundled_plugin/scripts/finalize_scan_contract.py +39 -0
- package/_bundled_plugin/scripts/generate_in_scope_files.py +134 -0
- package/_bundled_plugin/scripts/workbench_cli.py +33 -1
- package/_bundled_plugin/scripts/workbench_db.py +181 -118
- package/_bundled_plugin/scripts/workbench_feedback.py +2 -0
- package/_bundled_plugin/scripts/workbench_native_indexes.py +5 -49
- package/_bundled_plugin/scripts/workbench_progress.py +86 -3
- package/_bundled_plugin/scripts/workbench_remediation.py +19 -1
- package/_bundled_plugin/scripts/workbench_scan_history.py +7 -1
- package/_bundled_plugin/scripts/workbench_scan_start.py +11 -5
- package/_bundled_plugin/scripts/workbench_scan_usage.py +557 -0
- package/_bundled_plugin/scripts/workbench_schema.py +501 -0
- package/_bundled_plugin/scripts/workbench_target.py +14 -1
- package/_bundled_plugin/scripts/workbench_validation.py +117 -13
- package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +4 -4
- package/_bundled_plugin/skills/deep-security-scan/SKILL.md +34 -28
- package/_bundled_plugin/skills/finding-discovery/SKILL.md +1 -1
- package/_bundled_plugin/skills/security-diff-scan/SKILL.md +11 -8
- package/_bundled_plugin/skills/security-scan/SKILL.md +16 -9
- package/_bundled_plugin/skills/security-scan/references/repository-wide-scan.md +26 -14
- package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +1 -1
- package/_bundled_plugin/skills/threat-model/SKILL.md +2 -2
- package/_bundled_plugin/skills/validation/SKILL.md +5 -5
- package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +145 -227
- package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +53 -68
- package/dist/api.d.ts +30 -8
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +438 -66
- package/dist/api.js.map +1 -1
- package/dist/auth.d.ts.map +1 -1
- package/dist/auth.js +262 -44
- package/dist/auth.js.map +1 -1
- package/dist/cli.d.ts +4 -3
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +713 -148
- package/dist/cli.js.map +1 -1
- package/dist/config.d.ts +28 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +39 -2
- package/dist/config.js.map +1 -1
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +14 -0
- package/dist/contract.js.map +1 -1
- package/dist/cost.d.ts +7 -0
- package/dist/cost.d.ts.map +1 -1
- package/dist/cost.js +397 -26
- package/dist/cost.js.map +1 -1
- package/dist/errors.d.ts +2 -0
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +48 -0
- package/dist/errors.js.map +1 -1
- package/dist/index.d.ts +3 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/multiscan.d.ts +1 -0
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +5 -7
- package/dist/multiscan.js.map +1 -1
- package/dist/runtime.d.ts +40 -1
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +742 -46
- package/dist/runtime.js.map +1 -1
- package/dist/scan-activity.d.ts +13 -0
- package/dist/scan-activity.d.ts.map +1 -0
- package/dist/scan-activity.js +319 -0
- package/dist/scan-activity.js.map +1 -0
- package/dist/scan-dashboard.d.ts +47 -0
- package/dist/scan-dashboard.d.ts.map +1 -0
- package/dist/scan-dashboard.js +444 -0
- package/dist/scan-dashboard.js.map +1 -0
- package/dist/scan-history-renderer.d.ts.map +1 -1
- package/dist/scan-history-renderer.js +4 -1
- package/dist/scan-history-renderer.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/version.js.map +1 -1
- package/dist/worker-progress.d.ts +7 -0
- package/dist/worker-progress.d.ts.map +1 -1
- package/dist/worker-progress.js +68 -0
- package/dist/worker-progress.js.map +1 -1
- package/package.json +3 -3
|
@@ -1,104 +1,89 @@
|
|
|
1
1
|
# Vulnerability Report Format
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Write one self-contained Markdown report for a technically experienced security engineer who has not seen the original finding. The report should read like one careful researcher guiding another from the affected component and attacker prerequisites through the exact vulnerable source, demonstrated impact and appropriate fix.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
Don't just choose the name `report.md` or anything nondescript like that.
|
|
5
|
+
Use the language and locale requested by the user, or their normal default when unstated, with a warm professional voice and direct technical language. Let `we` guide real reasoning: carry the same input, object or state between relevant excerpts and explain why each step matters. Use `I` only for what the author actually reviewed, built, ran, observed or could not test. Explain the expected behaviour and the actual failure in plain language.
|
|
7
6
|
|
|
8
|
-
|
|
7
|
+
Use a specific report filename, such as `freebsd-shm-ftruncate-uaf.md`. Cite repository-relative paths, functions and verified release versions. Give fenced source excerpts the correct language. Use one natural source line per instruction paragraph or list item; do not hard-wrap Markdown prose in the middle of a sentence.
|
|
9
8
|
|
|
10
|
-
|
|
11
|
-
"we can now compare this with the fixed path". Use that voice in the real source, exploitability, and PoC walkthrough—not only in an introduction or summary.
|
|
9
|
+
## Evidence and voice
|
|
12
10
|
|
|
13
|
-
|
|
14
|
-
"I reproduced this on", "I did not get a stable shell", or "I could not exercise this path without a kernel fault-injection hook". Every report must include a truthful singular account of its validation basis. Static source review counts; do not imply that code was built or executed when it was not.
|
|
15
|
-
Never invent personal observations.
|
|
11
|
+
Start with evidence, not confidence. Before calling a finding exploitable, establish the assessed software version, configuration, attacker capability, reachable path, the security behaviour that should have held and the narrowest demonstrated boundary crossing. Open with the actual attack in ordinary language: name Mallory's legitimate starting credential or input, the separate owner or policy she crosses and the real sink she reaches. Immediately state important non-claims, such as that she reused her own session rather than stealing someone else's or breaking a protocol. Treat supplied notes, unexecuted PoCs and reported traces as claims until the underlying source or runtime artefact is actually inspected.
|
|
16
12
|
|
|
17
|
-
|
|
13
|
+
Introduce classic named actors when they clarify the story: Alice is the legitimate owner, Bob is another legitimate user or intended recipient, Mallory is the active attacker, and Eve is a passive eavesdropper. Carry `alice`, `bob`, `mallory` and `eve` into example account names, requests, commands and PoC output. Introduce only the actors the actual vulnerability needs and preserve the product's real account roles and permissions.
|
|
18
14
|
|
|
19
|
-
|
|
15
|
+
Keep the differences between exact source, inspected PoC code, observed execution, supplied reports, inference and unknowns clear in natural prose. Do not mechanically prefix every sentence with an evidence label or add a generic confidence disclaimer to every section.
|
|
20
16
|
|
|
21
|
-
|
|
17
|
+
Do not describe supporting material as a "witness". Name the specific thing the reader can inspect: a source excerpt showing the missing check, Mallory's request for Alice's document, the server response disclosing that document, a failing test, an input that triggers memory corruption, a captured execution trace, or an observed PoC result. Explain what that particular example establishes. If a genuine source symbol or required field is literally named `witness`, quote it accurately and immediately explain its actual purpose.
|
|
22
18
|
|
|
23
|
-
|
|
19
|
+
Trace the vulnerable behaviour back to its introducing change, inspect release tags and maintained branches, and verify fixed releases or backports. Do not let a shallow checkout end the investigation when complete history or exact release archives can be obtained safely. Tell that history primarily through public version numbers, and explain what the introducing change was meant to fix when that explains the root cause. Give the first affected and first fixed release only when confirmed against actual release snapshots. When older tags, history or branch coverage are unavailable, say `the earliest version I could verify` rather than inventing a definitive affected range; name unsampled patch releases or branch tips instead of implying they were checked.
|
|
24
20
|
|
|
25
|
-
-
|
|
26
|
-
- walk the reader through the relevant call chain or state machine before naming the bug;
|
|
27
|
-
- use short source snippets with file paths and function names, then explain the important lines in prose;
|
|
28
|
-
- show the bad state with concrete values, type conversions, lifetime edges,
|
|
29
|
-
bounds, lock transitions, parser states, or protocol fields;
|
|
30
|
-
- compare the fixed source shape when a fix exists, and explain the invariant the fix restores;
|
|
31
|
-
- treat exploitability as research, not a verdict. Discuss promising paths,
|
|
32
|
-
constraints, architecture or configuration dependencies, and dead ends that clarify the primitive;
|
|
33
|
-
- include small probes or exploratory PoCs when they helped refine the final exploit story;
|
|
34
|
-
- ship a clean final PoC with build/run commands and representative output.
|
|
21
|
+
Do not invent an affected-version range, introduction date, fixed release, deployment prevalence, default configuration, reliable race, root shell, tenant crossing, CVE, CVSS score, log or expected result. A documented configuration establishes that the configuration exists; it does not establish that most deployments enable it. A timing-controlled test establishes a controlled ordering; it does not establish production reliability.
|
|
35
22
|
|
|
36
|
-
|
|
23
|
+
Avoid abstract security jargon, grand claims, dramatic severity language, marketing phrasing, repetitive signposting, empty praise, token `we can see` sentences and conclusions disconnected from the evidence. Describe what should have happened, what happens instead and why it affects Alice or benefits Mallory. Prefer the exact small fact that the source proves.
|
|
37
24
|
|
|
38
|
-
|
|
25
|
+
Do not fill the report with Git hashes. Pin the exact source privately, cite the public software version and relevant repository-relative path in the report, and mention a short commit reference only when a specific introducing or fixing change genuinely matters or when no released version exists.
|
|
39
26
|
|
|
40
|
-
|
|
27
|
+
Never include an author-machine-specific absolute filesystem path anywhere in the distributable report or PoC. This applies to prose, source citations, links, shell commands, build files, comments, screenshots and captured terminal output. Use repository-relative or report-relative paths and remove local user-home, temporary, checkout and `file://` paths from included material. Preserve an absolute target-system path such as `/etc/passwd`, `/proc`, `/dev`, or a Unix-domain socket when that path is necessary to describe or reproduce the verified vulnerability.
|
|
41
28
|
|
|
42
|
-
The report
|
|
43
|
-
a terse triage note, or a stitched-together collection of bullets. The reader should be guided through the component, the reachable entry point, the vulnerable transition, the bad state, exploitation options, PoC behavior, and the fix in a coherent order.
|
|
29
|
+
The final report must contain the following seven headings, in this order.
|
|
44
30
|
|
|
45
|
-
|
|
31
|
+
## Executive Summary
|
|
46
32
|
|
|
47
|
-
|
|
48
|
-
bad transformation or lifetime edge, sink, and fixed source shape.
|
|
49
|
-
- Source snippets are short and purposeful. Each snippet should be introduced or explained so the important lines are obvious without opening the repository.
|
|
50
|
-
- Exploitability is explored like research. Discuss attacker-controlled values, useful primitives, realistic routes, constraints, fallbacks,
|
|
51
|
-
reliability dependencies, and dead ends that clarify the primitive.
|
|
52
|
-
- PoC material is first-class. Separate diagnostic probes from the strongest final demonstration when both are included, give a safe-first run order,
|
|
53
|
-
and include representative output.
|
|
54
|
-
- Remediation explains the invariant to restore before showing code. It should also name regression tests that exercise the real vulnerable path and nearby variants.
|
|
55
|
-
- The tone is calm, precise, and conversationally professional: confident enough to be useful, careful enough not to overclaim. The voice should feel like a researcher writing to peers, with natural "we" walkthrough language and honest "I" statements for experiments actually performed.
|
|
56
|
-
- The prose contains the connective reasoning between source excerpts and conclusions. A report that has all required headings but reduces the bug to a sequence of snippets, terse facts, and verdicts is still incomplete.
|
|
57
|
-
- The validation basis is personal and precise: what I inspected, built, ran,
|
|
58
|
-
observed, or could not test. The rest of the technical story uses "we" to make difficult control flow and exploitation reasoning comfortable to follow.
|
|
33
|
+
Name the component, assessed software version, required attacker position, essential configuration, vulnerable operation and narrowest demonstrated impact. State the verified first affected release, affected release range and fixed release when established by source history and inspected release snapshots. Distinguish the earliest release inspected from an unproven first affected version, and separate a plausible stronger effect from a demonstrated one.
|
|
59
34
|
|
|
60
|
-
|
|
35
|
+
Use the first paragraph to tell the concrete attack and its limits, not to announce a generic vulnerability class. Say who Mallory is, what legitimate access she starts with, which separate boundary should stop her, what happens instead and whether this is distinct from session theft, a protocol flaw or another tempting but unsupported explanation.
|
|
61
36
|
|
|
62
|
-
|
|
37
|
+
Include a truthful first-person statement of the validation basis. For example: `I reviewed the affected release, its earlier release history and the fix directly; I did not execute the trigger because no disposable test machine was available.` Do not imply that source review reproduced an exploit.
|
|
63
38
|
|
|
64
|
-
|
|
65
|
-
briefly, the relevant part of the software functionality. Assume the audience is technically strong, but not necessarily intimately familiar with the relevant part of the attack surface or threat model (including actors). This section should introduce the objects, callbacks, permission model, configuration, and normal invariants needed to understand the bug.
|
|
66
|
-
Use source snippets here when they establish the reachable surface or the security boundary.
|
|
39
|
+
## Background
|
|
67
40
|
|
|
68
|
-
|
|
41
|
+
Introduce only the component behaviour, named actors, controlled values, ownership, privilege boundary and expected security behaviour needed to understand this finding. Put the complete tested topology and prerequisites near the beginning. Separate default behaviour from opt-in configuration and deployment assumptions without guessing prevalence.
|
|
69
42
|
|
|
70
|
-
|
|
71
|
-
E.g. dropping to a stable interactive root shell, or confidently leaking a pointer to something useful, or achieving reliable command injection, etc.
|
|
72
|
-
(this will vary according to what the vulnerability is). Include multiple realistic exploitation routes when they exist. It is useful to preserve failed or partial branches when they teach an important constraint, such as allocator behavior, address-space layout, sandbox permissions, protocol sequencing, or object lifetime.
|
|
43
|
+
If the attack involves similar objects or values, name them concretely and preserve that distinction throughout the report. For example, distinguish `alice`'s document from Mallory's authenticated `mallory` session. Include a short source excerpt only when it establishes the real entry point, security boundary or normal behaviour.
|
|
73
44
|
|
|
74
|
-
|
|
75
|
-
reliability constraints, and dead ends when they sharpen the conclusion.
|
|
76
|
-
Spend prose on the hard or surprising parts; do not pad simple mechanics.
|
|
45
|
+
## Vulnerability Details
|
|
77
46
|
|
|
78
|
-
|
|
47
|
+
Follow the reported trigger in causal order. Begin with Mallory's actual controlled input. When source is available, inspect each material check or state change and show the precise line where the code fails to enforce the expected behaviour. When the user explicitly accepted a report-only assessment without source, describe the supplied trigger sequence as conditional, identify its actual evidence and unavailable checks, and never invent a source excerpt, line or observed state. First establish any verified ordinary policy or ownership check, then describe the evidenced shared state, receiving component or dependency decision and downstream operation without upgrading an unverified claim. Carry the same request, object, field or state through that whole path. When a named attacker does not fit the actual mechanism, describe the real actor without forcing the example.
|
|
79
48
|
|
|
80
|
-
|
|
81
|
-
Include a minimal code snippet on a proposed patch that would fix it. Also make suggestions about how the surrounding structure or other parts of the project could be improved or hardened to prevent the vulnerability. Explain the invariant in plain technical terms before showing the patch, and point to regression tests that would catch the original failure and nearby variants. This is a good location to include diagrams or flow charts, for instance.
|
|
49
|
+
For each available, verified source excerpt, identify its repository-relative source path, function and assessed software version. For a runtime-tested vendor or distribution package, verify excerpts and line numbers against that exact patched source; do not quote a nearby upstream tag as if it ran. Cite available dependency code in causal order and explain concrete log or trace fields in plain English. Quote only the lines necessary to establish the decisive behaviour, then explain what they prove and what remains unverified; omit source excerpts entirely when an explicitly accepted report-only assessment has no source. Refer to each demonstration by what it actually is, such as `Mallory's request`, `the returned document`, `the failing test` or `the execution trace`, rather than using an unexplained evidence label. Address relevant validation, locking, cancellation, cleanup, permissions, timing and alternative explanations rather than assuming they cannot prevent the path.
|
|
82
50
|
|
|
83
|
-
|
|
84
|
-
complex or underprotected.
|
|
51
|
+
When release history is available, explain how the vulnerable behaviour entered the project and which released versions contain it; otherwise identify the unavailable history and do not guess affected releases. Use a commit reference only where the introduction or fix is materially relevant to that explanation.
|
|
85
52
|
|
|
86
|
-
|
|
53
|
+
If the exact source contradicts the claimed sequence, explicitly say so. Do not silently replace the finding with a nearby weaker bug or a more convenient test event.
|
|
87
54
|
|
|
88
|
-
|
|
55
|
+
## Exploitability Analysis
|
|
56
|
+
|
|
57
|
+
Start with the narrow primitive the evidence actually establishes. Explain which account, privilege, tenant, process, memory object or availability boundary it can cross under the verified prerequisites.
|
|
58
|
+
|
|
59
|
+
Discuss stronger exploitation routes only where the underlying source or authorised experiments support their premises. Explain meaningful constraints such as allocator behaviour, controllable bytes, protocol ordering, configuration, scheduling and cleanup. Label a possible chain or timing window as conditional when it has not been demonstrated.
|
|
60
|
+
|
|
61
|
+
When an authorized disposable target or a verified execution trace is available, include positive and negative controls that rule out the strongest alternative explanations: show normal allowed access, fresh rejection at the crossed boundary, same-domain success where relevant, the real sink reached only by the attack and any one-setting mitigation that was actually tested. Explain what each observed control rules out. When execution or a verified trace is unavailable, describe relevant controls as unperformed validation work rather than implying runtime observations. Do not turn ordinary reachability into remote code execution, an artificial interleaving into production reliability or a different identity into privilege escalation.
|
|
62
|
+
|
|
63
|
+
## Proof of Concept
|
|
64
|
+
|
|
65
|
+
Identify the real PoC artefacts, target requirements, build steps, execution safety and expected state. Use consistent example account names such as `alice` and `mallory`. Separate exact source review, preserved run records, offline evidence verification, PoC code that was inspected, a syntax or build check that succeeded, a convenience reproducer that was assembled but not run, source-confirmed releases and a run that was actually observed.
|
|
66
|
+
|
|
67
|
+
Use relative commands from the distributable report directory, for example:
|
|
89
68
|
|
|
90
69
|
```sh
|
|
91
70
|
cd poc
|
|
92
71
|
make
|
|
93
|
-
./
|
|
72
|
+
./poc
|
|
94
73
|
```
|
|
95
74
|
|
|
96
|
-
|
|
75
|
+
Include command output only when generated by the author or directly verified in a supplied trace. Explain what each request, response, test run or output line actually shows instead of referring to it as a "witness". Remove local absolute paths from genuine captured output without inventing results; visibly mark a necessary omission if it matters. If execution was unavailable or unsafe, say why; describe the unobserved result explicitly as expected behaviour, not a successful run. Never fabricate a crash, shell, leaked value, log or fixed-target result.
|
|
97
76
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
77
|
+
Explain any cleanup and warn clearly when a PoC could corrupt data, exhaust resources, crash a machine or change privileges. If no real PoC can safely be developed, explain the limitation instead of inventing an artefact.
|
|
78
|
+
|
|
79
|
+
## Remediation
|
|
80
|
+
|
|
81
|
+
Explain in plain English what the fixed code must do: for example, check that the requested document belongs to Alice before returning it to the signed-in user, or accept a resumed session only when the current effective authentication policy also accepts the identity recorded in it. Name every policy input that must remain distinct, preserve that distinction through serialisation or restoration and include it in shared lookup keys where relevant. Provide a small, source-compatible proposed fix when the surrounding source supports it, or cite and explain an inspected upstream fix. Clearly distinguish proposed remediation from a fix that has actually shipped and identify the verified fixed release when known.
|
|
82
|
+
|
|
83
|
+
Recommend regression tests covering the real entry point, the failing state transition, a meaningful negative control and nearby variants where justified. Suggest broader hardening only when it addresses the demonstrated mechanism.
|
|
84
|
+
|
|
85
|
+
## Summary
|
|
86
|
+
|
|
87
|
+
Restate the verified prerequisites, actual security failure, affected versions and demonstrated impact without upgrading any earlier conditional claim. Briefly identify the most useful remaining validation, exploitation question or related source path only when grounded in the evidence.
|
|
103
88
|
|
|
104
|
-
|
|
89
|
+
The report and every file in any sibling `poc/` directory must remain understandable outside the author's environment. Check all Markdown, source, scripts, build recipes and included output for personal-machine and other local absolute paths. Do not include internal storage locations, scanner implementation detail, drafting workflow or placeholders. If the final disclosure package also includes a separate advisory, keep its format separate and validate the technical report through an isolated temporary directory or link so the advisory is not mistaken for a second technical report.
|
package/dist/api.d.ts
CHANGED
|
@@ -5,7 +5,8 @@ import { type ScanCost } from "./cost.js";
|
|
|
5
5
|
import { type ScanExpectation } from "./contract.js";
|
|
6
6
|
import { ScanResult } from "./result.js";
|
|
7
7
|
import type { SeverityLevel } from "./models.js";
|
|
8
|
-
import { type
|
|
8
|
+
import { type ScanActivity } from "./scan-activity.js";
|
|
9
|
+
import { type ScanProgress, type ScanWorkerStatus } from "./worker-progress.js";
|
|
9
10
|
import { importAmbientAuth, type ProcessEnvironment } from "./runtime.js";
|
|
10
11
|
import { type NormalizedTarget, type ScanMode, type ScanTarget } from "./targets.js";
|
|
11
12
|
interface CodexThreadLike {
|
|
@@ -20,7 +21,13 @@ interface ScanEvent {
|
|
|
20
21
|
readonly type: string;
|
|
21
22
|
readonly [key: string]: unknown;
|
|
22
23
|
}
|
|
23
|
-
export interface
|
|
24
|
+
export interface DeepScanOptions {
|
|
25
|
+
workers?: number;
|
|
26
|
+
subagents?: number;
|
|
27
|
+
stopAfterNoNew?: number;
|
|
28
|
+
maxDiscoveryRuns?: number;
|
|
29
|
+
}
|
|
30
|
+
export interface ScanOptions extends DeepScanOptions {
|
|
24
31
|
auth?: ScanAuthMode;
|
|
25
32
|
target?: ScanTarget;
|
|
26
33
|
mode?: ScanMode;
|
|
@@ -35,28 +42,36 @@ export interface ScanOptions {
|
|
|
35
42
|
onOutputArchived?: (archiveDir: string) => void;
|
|
36
43
|
onOutputDirReady?: (scanDir: string) => void;
|
|
37
44
|
onAuthentication?: (authentication: ScanAuthentication) => void;
|
|
45
|
+
onTrustedAccessStatus?: (status: ScanTrustedAccessStatus) => void;
|
|
38
46
|
onScanStarted?: () => void;
|
|
39
47
|
onReconnect?: (attempt: number, maxAttempts: number, details?: ScanReconnectDetails) => void;
|
|
48
|
+
onActivity?: (activity: ScanActivity) => void;
|
|
49
|
+
onProgress?: (progress: ScanProgress) => void;
|
|
40
50
|
onWorkerStatus?: (status: ScanWorkerStatus) => void;
|
|
41
|
-
onWarning?: (warning: string) => void;
|
|
51
|
+
onWarning?: (warning: string, details?: ScanWarningDetails) => void;
|
|
42
52
|
onObserverError?: (observer: ScanObserverName, error: unknown) => void;
|
|
43
53
|
signal?: AbortSignal;
|
|
44
54
|
}
|
|
45
55
|
export type ScanAuthMode = "auto" | "chatgpt" | "api-key";
|
|
46
56
|
export type ScanAuthentication = {
|
|
47
57
|
method: "api_key";
|
|
48
|
-
source: "OPENAI_API_KEY" | "CODEX_API_KEY";
|
|
58
|
+
source: "OPENAI_API_KEY" | "CODEX_API_KEY" | "OPENROUTER_API_KEY" | "FIREWORKS_API_KEY";
|
|
49
59
|
verified: false;
|
|
50
60
|
} | {
|
|
51
61
|
method: "stored_credentials";
|
|
62
|
+
credentialType?: "api_key" | "chatgpt";
|
|
52
63
|
verified: false;
|
|
53
64
|
};
|
|
65
|
+
export type ScanTrustedAccessStatus = "granted" | "not_granted" | "unknown";
|
|
54
66
|
export interface ScanReconnectDetails {
|
|
55
67
|
reason: "rate_limit" | "network" | "authentication" | "authorization";
|
|
56
68
|
retryAfterSeconds?: number;
|
|
57
69
|
}
|
|
58
|
-
|
|
59
|
-
|
|
70
|
+
export interface ScanWarningDetails {
|
|
71
|
+
kind: "target_changed";
|
|
72
|
+
}
|
|
73
|
+
type ScanObserverName = "onAuthentication" | "onCost" | "onOutputArchived" | "onOutputDirReady" | "onScanStarted" | "onTrustedAccessStatus" | "onReconnect" | "onActivity" | "onProgress" | "onWorkerStatus" | "onWarning";
|
|
74
|
+
export interface ScanPreflight extends DeepScanOptions {
|
|
60
75
|
repository: string;
|
|
61
76
|
target: NormalizedTarget;
|
|
62
77
|
mode: ScanMode;
|
|
@@ -65,6 +80,7 @@ export interface ScanPreflight {
|
|
|
65
80
|
archiveDir?: string;
|
|
66
81
|
authentication: ScanAuthentication;
|
|
67
82
|
model: string;
|
|
83
|
+
modelProvider?: string;
|
|
68
84
|
reasoningEffort: string;
|
|
69
85
|
maxCostUsd?: number;
|
|
70
86
|
}
|
|
@@ -97,20 +113,26 @@ interface ScanEventRunOptions {
|
|
|
97
113
|
scanDir: string;
|
|
98
114
|
pluginRoot: string;
|
|
99
115
|
expectation: ScanExpectation;
|
|
116
|
+
authentication?: ScanAuthentication;
|
|
100
117
|
workbenchValidated?: boolean;
|
|
101
118
|
model?: string;
|
|
119
|
+
expectedFilesTotal?: number;
|
|
102
120
|
onFinalize?: (usage: unknown) => Promise<unknown>;
|
|
103
121
|
onThreadStarted?: (threadId: string) => void;
|
|
104
122
|
onScanStarted?: () => void;
|
|
123
|
+
onTrustedAccessStatus?: (status: ScanTrustedAccessStatus) => void;
|
|
105
124
|
onReconnect?: (attempt: number, maxAttempts: number, details?: ScanReconnectDetails) => void;
|
|
125
|
+
onActivity?: (activity: ScanActivity) => void;
|
|
126
|
+
onProgress?: (progress: ScanProgress) => void;
|
|
106
127
|
onWorkerStatus?: (status: ScanWorkerStatus) => void;
|
|
128
|
+
onWarning?: (warning: string) => void;
|
|
107
129
|
onObserverError?: (observer: ScanObserverName, error: unknown) => void;
|
|
108
130
|
}
|
|
109
131
|
export declare function runScanEvents(options: ScanEventRunOptions): Promise<ScanResult>;
|
|
110
|
-
export declare function scanAuthentication(environment: ProcessEnvironment, auth?: ScanAuthMode): ScanAuthentication;
|
|
132
|
+
export declare function scanAuthentication(environment: ProcessEnvironment, auth?: ScanAuthMode, modelProvider?: unknown): ScanAuthentication;
|
|
111
133
|
export declare function classifyConnectionFailure(error: unknown): "rate_limited" | "unauthorized" | "forbidden" | "network_error" | "timeout" | "unknown";
|
|
112
134
|
export declare function scanRuntimeCodexConfig(config: JsonObject, stateDirectory: string, protectedCredentialHome?: string): JsonObject;
|
|
113
|
-
export declare function scanPreflightCodexConfig(config: JsonObject): JsonObject;
|
|
135
|
+
export declare function scanPreflightCodexConfig(config: JsonObject, activeProjectPath?: string): JsonObject;
|
|
114
136
|
export declare function environmentValue(environment: ProcessEnvironment, requested: string): string | undefined;
|
|
115
137
|
export {};
|
|
116
138
|
//# sourceMappingURL=api.d.ts.map
|
package/dist/api.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":";
|
|
1
|
+
{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}
|