@openai/codex-security 0.1.12 → 0.1.14

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 (50) hide show
  1. package/README.md +161 -26
  2. package/_bundled_plugin/scripts/workbench_cli.py +4 -0
  3. package/_bundled_plugin/scripts/workbench_db.py +258 -0
  4. package/_bundled_plugin/scripts/workbench_scan_usage.py +26 -0
  5. package/_bundled_plugin/scripts/workbench_schema.py +40 -0
  6. package/dist/api.d.ts +1 -1
  7. package/dist/api.d.ts.map +1 -1
  8. package/dist/api.js +25 -7
  9. package/dist/api.js.map +1 -1
  10. package/dist/bulk-scan-discovery.d.ts +5 -1
  11. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  12. package/dist/bulk-scan-discovery.js +24 -7
  13. package/dist/bulk-scan-discovery.js.map +1 -1
  14. package/dist/cli.d.ts +3 -0
  15. package/dist/cli.d.ts.map +1 -1
  16. package/dist/cli.js +579 -19
  17. package/dist/cli.js.map +1 -1
  18. package/dist/config.d.ts +1 -0
  19. package/dist/config.d.ts.map +1 -1
  20. package/dist/config.js +8 -1
  21. package/dist/config.js.map +1 -1
  22. package/dist/contract.d.ts +12 -0
  23. package/dist/contract.d.ts.map +1 -1
  24. package/dist/contract.js +30 -2
  25. package/dist/contract.js.map +1 -1
  26. package/dist/index.d.ts +2 -0
  27. package/dist/index.d.ts.map +1 -1
  28. package/dist/index.js +1 -0
  29. package/dist/index.js.map +1 -1
  30. package/dist/publication-events.d.ts +16 -0
  31. package/dist/publication-events.d.ts.map +1 -0
  32. package/dist/publication-events.js +141 -0
  33. package/dist/publication-events.js.map +1 -0
  34. package/dist/publication-store.d.ts +5 -0
  35. package/dist/publication-store.d.ts.map +1 -0
  36. package/dist/publication-store.js +102 -0
  37. package/dist/publication-store.js.map +1 -0
  38. package/dist/publication.d.ts +27 -0
  39. package/dist/publication.d.ts.map +1 -0
  40. package/dist/publication.js +207 -0
  41. package/dist/publication.js.map +1 -0
  42. package/dist/publish.d.ts +77 -0
  43. package/dist/publish.d.ts.map +1 -0
  44. package/dist/publish.js +748 -0
  45. package/dist/publish.js.map +1 -0
  46. package/dist/scan-dashboard.d.ts +2 -0
  47. package/dist/scan-dashboard.d.ts.map +1 -1
  48. package/dist/scan-dashboard.js +25 -8
  49. package/dist/scan-dashboard.js.map +1 -1
  50. package/package.json +3 -2
package/README.md CHANGED
@@ -200,6 +200,7 @@ Trusted Access for Cyber. To apply or check your access, visit
200
200
  ## CLI
201
201
 
202
202
  ```bash
203
+ npx @openai/codex-security scan
203
204
  npx @openai/codex-security scan /path/to/repository
204
205
  npx @openai/codex-security scan /path/to/repository --headless
205
206
  npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra
@@ -223,17 +224,26 @@ npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside
223
224
  npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --scan-prompt-file scan.md --post-scan-prompt-file follow-up.md
224
225
  npx @openai/codex-security scans list /path/to/repository
225
226
  npx @openai/codex-security scans list --scan-root /path/outside/repository/results
227
+ npx @openai/codex-security scans show
226
228
  npx @openai/codex-security scans show SCAN_ID
229
+ npx @openai/codex-security scans logs
227
230
  npx @openai/codex-security scans logs SCAN_ID
231
+ npx @openai/codex-security scans rerun
228
232
  npx @openai/codex-security scans rerun SCAN_ID
229
233
  npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID
230
234
  npx @openai/codex-security scans match --all
235
+ npx @openai/codex-security scans compare
236
+ npx @openai/codex-security scans compare PREVIOUS_SCAN_ID
231
237
  npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID
238
+ npx @openai/codex-security findings
232
239
  npx @openai/codex-security findings list /path/to/repository
233
240
  npx @openai/codex-security findings false-positive OCCURRENCE_ID --reason "The route already checks permissions"
241
+ npx @openai/codex-security export
234
242
  npx @openai/codex-security export /path/outside/repository/results --export-format sarif --output /path/outside/repository/results.sarif
235
243
  npx @openai/codex-security export /path/outside/repository/results --export-format csv --output /path/outside/repository/findings.csv
236
244
  npx @openai/codex-security export /path/outside/repository/results --export-format json --output /path/outside/repository/findings.json
245
+ npx @openai/codex-security publish scan /path/outside/repository/results --to linear --linear-team TEAM_ID
246
+ npx @openai/codex-security publish scan --to linear --linear-team TEAM_ID
237
247
  npx @openai/codex-security validate /path/outside/repository/findings.json "Possible SQL injection in src/query.ts:42"
238
248
  npx @openai/codex-security validate "Possible SQL injection" --effort high
239
249
  npx @openai/codex-security patch /path/outside/repository/findings.json "Missing authorization check in src/routes.ts:18"
@@ -333,7 +343,8 @@ configuration. Each scan starts with a private runtime and these Codex
333
343
  defaults:
334
344
 
335
345
  ```toml
336
- approval_policy = "never"
346
+ approval_policy = "on-request"
347
+ approvals_reviewer = "auto_review"
337
348
  cli_auth_credentials_store = "auto"
338
349
  model = "gpt-5.6-sol"
339
350
  model_reasoning_effort = "xhigh"
@@ -383,8 +394,10 @@ and `features.multi_agent_v2.enabled=false` are incompatible and rejected.
383
394
  `model_reasoning_effort` `--codex` keys; they do not accept general scan
384
395
  runtime overrides.
385
396
 
386
- These overrides do not change the scan's approval policy or filesystem
387
- permissions. See [Local security model](#local-security-model).
397
+ These overrides cannot replace the scanner-owned approval reviewer or
398
+ filesystem profile. Use `--codex 'approval_policy="never"'` to deny approval
399
+ requests instead of reviewing them automatically. See
400
+ [Local security model](#local-security-model).
388
401
 
389
402
  ### Deep-scan engine configuration
390
403
 
@@ -424,6 +437,8 @@ The CLI and SDK recognize the following user-configurable environment:
424
437
  | Variable | Effect |
425
438
  | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
426
439
  | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan authentication; `OPENAI_API_KEY` wins when both are present. |
440
+ | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default Linear team and project for completed-scan publication. |
441
+ | `CODEX_SECURITY_LINEAR_API_KEY` | Publish directly to Linear with a personal API key; safer than a command-line key. |
427
442
  | `CODEX_SECURITY_LOG_LEVEL` | CLI-only; set to `debug` for verbose diagnostics. |
428
443
  | `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset. |
429
444
  | `CODEX_SECURITY_STATE_DIR` | Override the private scan-history, workbench, and default artifact directory. |
@@ -536,16 +551,129 @@ and scans stopped at their configured cost limit do not start another turn.
536
551
  invocation and defaults to `1`. Results remain under `--output-dir`; rerun the
537
552
  same command to resume.
538
553
 
554
+ ### Publish completed scans to Linear
555
+
556
+ Publish every finding from a completed standard, deep, or scoped scan to one
557
+ Linear team:
558
+
559
+ ```bash
560
+ npx @openai/codex-security publish scan /path/to/completed-scan \
561
+ --to linear \
562
+ --linear-team TEAM_ID
563
+ ```
564
+
565
+ Add `--project PROJECT_ID` to place the issues in a Linear project. Without a
566
+ project, issues are created directly in the selected team.
567
+
568
+ To choose from all completed scans saved in your local scan history, omit the
569
+ scan directory. The selector highlights each repository and shows its finding
570
+ count, relative run time, and abbreviated scan ID:
571
+
572
+ ```bash
573
+ npx @openai/codex-security publish scan \
574
+ --to linear \
575
+ --linear-team TEAM_ID
576
+ ```
577
+
578
+ Destination flags take precedence over `CODEX_SECURITY_LINEAR_TEAM` and the
579
+ optional `CODEX_SECURITY_LINEAR_PROJECT`. Use `--dry-run` to preview the issue
580
+ titles without creating them, or `--json` to return structured publication
581
+ results.
582
+ Interactive publication shows a full-screen activity view with live Codex
583
+ output and issue-creation progress. Other terminals receive plain progress on
584
+ stderr, so `--json` output remains machine-readable.
585
+
586
+ By default, publishing starts Codex with your existing Codex configuration and
587
+ connected Linear app. Sign in to Codex and connect Linear before publishing in
588
+ this mode. No separate Linear API token is required, and publication does not
589
+ use the isolated Codex home created for security scans.
590
+
591
+ To publish directly through the Linear API without starting Codex, configure a
592
+ Linear personal API key:
593
+
594
+ ```bash
595
+ export CODEX_SECURITY_LINEAR_API_KEY=YOUR_LINEAR_PERSONAL_API_KEY
596
+ npx @openai/codex-security publish scan /path/to/completed-scan \
597
+ --to linear \
598
+ --linear-team TEAM_ID
599
+ ```
600
+
601
+ Direct API publication leaves issues unassigned by default. Pass
602
+ `--linear-assignee teammate@example.com` or `--linear-assignee USER_ID` to
603
+ assign the issues to a Linear user by email address or user ID.
604
+ `--linear-assignee` requires direct API publication.
605
+
606
+ You can also pass `--linear-api-key KEY`, which takes precedence over
607
+ `CODEX_SECURITY_LINEAR_API_KEY`. Prefer the environment variable to avoid
608
+ exposing your API key in shell history and process listings. API keys are not
609
+ added to successful publication results, scan history, or sealed scan artifacts.
610
+ Error messages are preserved as returned. `--dry-run` never contacts Linear in
611
+ either mode.
612
+
613
+ Each finding creates a separate new issue titled
614
+ `[Codex Security][HIGH] Finding title`. The issue includes the scan ID,
615
+ repository, scanned scope, source locations and code snippets, severity,
616
+ confidence, vulnerability classification, summary, and remediation guidance.
617
+ Verified immutable Git revisions include source links. Findings are published
618
+ concurrently in batches of up to 20. Successful issue identifiers are linked
619
+ to their findings in the local scan-history database, and structured results
620
+ are read back from that database rather than generated by Codex. The completed
621
+ scan must already exist in the local scan history. Running publication again
622
+ creates another set of issues for the same scan; existing issues are not
623
+ matched, updated, or reused.
624
+
625
+ Issue descriptions contain source code and vulnerability details. Select a
626
+ Linear destination authorized to receive that information. Publication receipts
627
+ are stored separately from the sealed scan artifacts.
628
+
629
+ You can also publish a scan from TypeScript:
630
+
631
+ ```ts
632
+ import { publishScan } from "@openai/codex-security";
633
+
634
+ const publication = await publishScan("/path/to/completed-scan", {
635
+ destination: "linear",
636
+ teamId: "TEAM_ID",
637
+ onProgress: (progress) => {
638
+ if (progress.type === "issue_completed") {
639
+ console.error(
640
+ `Processed ${progress.completed} of ${progress.total} findings.`,
641
+ );
642
+ }
643
+ },
644
+ });
645
+
646
+ console.log(publication.scanId);
647
+ console.log(publication.created.length);
648
+ ```
649
+
650
+ Add `projectId: "PROJECT_ID"` to the options to publish into a specific Linear
651
+ project instead of directly to the team.
652
+
653
+ Pass `linearApiKey` to publish directly through the Linear API. Omit
654
+ `assigneeId` to leave issues unassigned, or supply a Linear user ID or email
655
+ address to select an assignee:
656
+
657
+ ```ts
658
+ const directPublication = await publishScan("/path/to/completed-scan", {
659
+ destination: "linear",
660
+ teamId: "TEAM_ID",
661
+ linearApiKey: process.env["CODEX_SECURITY_LINEAR_API_KEY"],
662
+ assigneeId: "teammate@example.com",
663
+ });
664
+ ```
665
+
539
666
  ### Scan history and reruns
540
667
 
541
- `npx @openai/codex-security scans list` lists scans for the current repository. Pass a
542
- repository path to inspect another checkout, `--scan-root DIR` to list scans
543
- whose artifacts are under a particular root. `scans show SCAN_ID` includes the
544
- scan configuration, results, coverage, and artifact locations. Add
668
+ `scans` or `scans list` lists scans for the current repository. Pass a repository
669
+ path to inspect another checkout, or `--scan-root DIR` to list scans whose
670
+ artifacts are under a particular root. `scans show` opens the latest completed
671
+ scan for the current repository. Pass `SCAN_ID` to inspect another scan. Scan
672
+ details include the configuration, results, coverage, and artifact locations. Add
545
673
  `--show-linked-findings` to include finding links from previous scans.
546
674
 
547
- `scans logs SCAN_ID` shows complete session events from the scan and its
548
- workers, which can include source code and credentials.
675
+ `scans logs` shows session events from the latest scan, including an active scan.
676
+ Pass `SCAN_ID` to select another scan. Logs can contain source code and credentials.
549
677
 
550
678
  Every scan history command accepts a full scan ID or a unique prefix of at
551
679
  least eight characters.
@@ -565,22 +693,25 @@ default directory, select a writable directory outside the scanned repository:
565
693
  export CODEX_SECURITY_STATE_DIR=/path/to/writable/codex-security-state
566
694
  ```
567
695
 
568
- Use `findings false-positive OCCURRENCE_ID --reason TEXT` to mark a finding as
569
- a false positive and explain why. Later scans dismiss a matching finding only
570
- when the same reason still applies.
696
+ `findings` or `findings list` lists open findings for the current repository.
697
+ Use `findings false-positive OCCURRENCE_ID --reason TEXT` to mark a finding as a
698
+ false positive and explain why. Later scans dismiss a matching finding only when
699
+ the same reason still applies.
571
700
 
572
- `scans rerun SCAN_ID` repeats the original configuration against the current
573
- checkout so a fixed vulnerability can be checked again.
701
+ `scans rerun` repeats the latest completed scan against the current checkout.
702
+ Pass `SCAN_ID` to rerun another scan.
574
703
 
575
704
  `scans match BEFORE_SCAN_ID AFTER_SCAN_ID` links findings with the same root
576
705
  cause; `scans match --all` matches all completed scans of the current repository,
577
706
  including other worktrees and clones. Saved matches appear in `scans show` and
578
707
  are reused unless `--force` is passed. Scans without sealed artifacts are skipped.
579
708
 
580
- `scans compare BEFORE_SCAN_ID AFTER_SCAN_ID` automatically matches findings by
581
- root cause, reuses saved matches, and reports findings as new, persisting,
582
- reopened, resolved, or unknown. Missing findings are not treated as resolved when
583
- the later scan is incomplete or does not cover their original scope.
709
+ `scans compare` compares the two latest completed scans. Pass one scan ID to
710
+ compare it with the latest completed scan, or two IDs to select both scans. It
711
+ matches findings by root cause, reuses saved matches, and reports findings as
712
+ new, persisting, reopened, resolved, or unknown. Missing findings are not
713
+ treated as resolved when the later scan is incomplete or does not cover their
714
+ original scope.
584
715
 
585
716
  The CLI uses [Incur](https://github.com/wevm/incur) for agent-friendly discovery
586
717
  and structured output. Inspect the command manifest with `--llms`, inspect a
@@ -612,7 +743,8 @@ they do not produce structured CLI output. Sign-in commands remain interactive.
612
743
  CSV exports cannot be written to stdout while JSON output is requested.
613
744
 
614
745
  Use `export` to create CSV, JSON, or SARIF from a completed, sealed scan without
615
- starting Codex or loading credentials. JSON preserves the sealed findings
746
+ starting Codex or loading credentials. Without a scan directory, it exports the
747
+ latest completed scan for the current repository. JSON preserves the sealed findings
616
748
  document. CSV uses the portable findings columns, marks findings as open, and
617
749
  does not include local workbench triage state. The exporter validates the seal
618
750
  before writing, accepts `--output -` for stdout, and can use
@@ -699,13 +831,16 @@ repository, Git installation, configured tools, and other scans under the
699
831
  same account are not separate security principals.
700
832
 
701
833
  Every scan uses the `codex_security_scan` filesystem profile and
702
- `approvalPolicy: "never"`. Its profile allows reads of the local filesystem and
703
- writes to workspace roots and the selected scan state directory. Scans do not
704
- request interactive approval or grant filesystem escalations. Setting
705
- `approval_policy`, `approvals_reviewer`, `sandbox_mode`, or permissions
706
- through `--codex` or SDK `codexOverrides` does not replace these controls or
707
- make the filesystem profile more restrictive. Independently enforced host and
708
- network restrictions still apply.
834
+ automatically reviewed execution approvals. Its baseline profile allows reads
835
+ of the local filesystem and writes to workspace roots and the selected scan
836
+ state directory. Approval requests are reviewed without an interactive prompt;
837
+ approved requests can grant additional permissions for a specific operation.
838
+ Use `--codex 'approval_policy="never"'` or a selected profile with that policy
839
+ to deny all requests instead. Other `approval_policy`, `approvals_reviewer`,
840
+ `sandbox_mode`, or permission overrides cannot replace the reviewer or baseline
841
+ filesystem profile. Saved scans retain their effective approval policy; older
842
+ saved scans remain deny-all when rerun. Independently enforced host and network
843
+ restrictions still apply.
709
844
 
710
845
  Scan and workbench subprocesses can inherit your environment, including
711
846
  unrelated API tokens and cloud credentials. Start a scan with only the
@@ -304,6 +304,10 @@ def parse_args(description: str) -> argparse.Namespace:
304
304
  export_findings.add_argument("--scan-id", required=True)
305
305
  export_findings.add_argument("--format", choices=EXPORT_FORMATS, required=True)
306
306
 
307
+ for command in ("prepare-linear-publication", "record-linear-publications"):
308
+ publication = subparsers.add_parser(command)
309
+ publication.add_argument("--input-file", required=True)
310
+
307
311
  subparsers.add_parser("database-info")
308
312
  return parser.parse_args()
309
313
 
@@ -1443,6 +1443,8 @@ def complete_scan_locked(
1443
1443
  verify_manifest_binding(scan, manifest)
1444
1444
  manifest_digest = published_manifest_digest(scan_dir, manifest)
1445
1445
  pin_legacy_manifest_digest(connection, scan["id"], manifest_digest)
1446
+ if cost_json is not None and scan["recipe_json"] is not None:
1447
+ scan_usage.reconcile_completed_scan_cost(connection, scan, cost_json)
1446
1448
  return scan_context(connection, scan["id"])
1447
1449
  if scan["status"] != "running":
1448
1450
  raise SystemExit("Only a running scan can be completed.")
@@ -2403,6 +2405,258 @@ def set_finding_remediation(
2403
2405
  return scan_context(connection, occurrence["scan_id"])
2404
2406
 
2405
2407
 
2408
+ def linear_publication_input(
2409
+ args: argparse.Namespace, *, recording: bool
2410
+ ) -> tuple[dict[str, Any], dict[str, str], list[dict[str, str]]]:
2411
+ payload = read_json_object(Path(args.input_file))
2412
+ required = {"scanId", "scanDirectory", "destination", "findings"}
2413
+ if recording:
2414
+ required.add("publications")
2415
+ if set(payload) != required:
2416
+ raise SystemExit("Linear publication input contains unexpected or missing fields.")
2417
+
2418
+ scan_id = payload["scanId"]
2419
+ scan_directory = payload["scanDirectory"]
2420
+ destination = payload["destination"]
2421
+ findings = payload["findings"]
2422
+ if not isinstance(scan_id, str) or not isinstance(scan_directory, str):
2423
+ raise SystemExit("Linear publication input must identify the exact completed scan.")
2424
+ if (
2425
+ not isinstance(destination, dict)
2426
+ or not {"type", "teamId"}.issubset(destination)
2427
+ or not set(destination).issubset({"type", "teamId", "projectId"})
2428
+ or destination.get("type") != "linear"
2429
+ or not isinstance(destination.get("teamId"), str)
2430
+ or not destination["teamId"].strip()
2431
+ or (
2432
+ "projectId" in destination
2433
+ and (
2434
+ not isinstance(destination["projectId"], str)
2435
+ or not destination["projectId"].strip()
2436
+ )
2437
+ )
2438
+ ):
2439
+ raise SystemExit("Linear publication input must identify the exact team and optional project.")
2440
+ if not isinstance(findings, list):
2441
+ raise SystemExit("Linear publication input must include the planned scan findings.")
2442
+
2443
+ seen_finding_ids: set[str] = set()
2444
+ seen_occurrence_ids: set[str] = set()
2445
+ for finding in findings:
2446
+ if (
2447
+ not isinstance(finding, dict)
2448
+ or set(finding) != {"findingId", "occurrenceId"}
2449
+ or not isinstance(finding.get("findingId"), str)
2450
+ or not finding["findingId"].strip()
2451
+ or not isinstance(finding.get("occurrenceId"), str)
2452
+ or not finding["occurrenceId"].strip()
2453
+ ):
2454
+ raise SystemExit("Linear publication input contains an invalid finding identity.")
2455
+ if (
2456
+ finding["findingId"] in seen_finding_ids
2457
+ or finding["occurrenceId"] in seen_occurrence_ids
2458
+ ):
2459
+ raise SystemExit("Linear publication input repeats a finding or occurrence.")
2460
+ seen_finding_ids.add(finding["findingId"])
2461
+ seen_occurrence_ids.add(finding["occurrenceId"])
2462
+
2463
+ return payload, destination, findings
2464
+
2465
+
2466
+ def verify_linear_publication_scan(
2467
+ connection: sqlite3.Connection,
2468
+ payload: dict[str, Any],
2469
+ findings: list[dict[str, str]],
2470
+ ) -> sqlite3.Row:
2471
+ try:
2472
+ scan = require_scan(connection, payload["scanId"])
2473
+ except SystemExit as exc:
2474
+ raise SystemExit(
2475
+ "The completed scan is not present in the local Codex Security scan-history database. "
2476
+ "Use the state directory where the scan was completed."
2477
+ ) from exc
2478
+ if scan["id"] != payload["scanId"]:
2479
+ raise SystemExit("Linear publication must use the exact completed scan identifier.")
2480
+ if scan["status"] != "complete":
2481
+ raise SystemExit("Only completed scans can publish findings to Linear.")
2482
+
2483
+ requested_directory = require_canonical_scan_directory(Path(payload["scanDirectory"]))
2484
+ recorded_directory = require_canonical_scan_directory(Path(scan["scan_dir"]))
2485
+ if os.path.normcase(requested_directory) != os.path.normcase(recorded_directory):
2486
+ raise SystemExit(
2487
+ "The selected scan directory does not match its local Codex Security scan history."
2488
+ )
2489
+
2490
+ stored_findings = {
2491
+ row["id"]: row["finding_id"]
2492
+ for row in connection.execute(
2493
+ "SELECT id, finding_id FROM finding_occurrences WHERE scan_id = ?",
2494
+ (scan["id"],),
2495
+ )
2496
+ }
2497
+ for finding in findings:
2498
+ if stored_findings.get(finding["occurrenceId"]) != finding["findingId"]:
2499
+ raise SystemExit(
2500
+ "A selected finding or occurrence does not belong to the completed scan "
2501
+ "in local Codex Security scan history."
2502
+ )
2503
+ if len(stored_findings) != len(findings):
2504
+ raise SystemExit(
2505
+ "The completed scan findings do not exactly match local Codex Security scan history."
2506
+ )
2507
+ return scan
2508
+
2509
+
2510
+ def prepare_linear_publication(
2511
+ connection: sqlite3.Connection, args: argparse.Namespace
2512
+ ) -> dict[str, Any]:
2513
+ payload, destination, findings = linear_publication_input(args, recording=False)
2514
+ connection.execute("BEGIN IMMEDIATE")
2515
+ try:
2516
+ scan = verify_linear_publication_scan(connection, payload, findings)
2517
+ result = {
2518
+ "scanId": scan["id"],
2519
+ "destination": destination,
2520
+ "findingCount": len(findings),
2521
+ }
2522
+ connection.commit()
2523
+ except BaseException:
2524
+ connection.rollback()
2525
+ raise
2526
+ return result
2527
+
2528
+
2529
+ def record_linear_publications(
2530
+ connection: sqlite3.Connection, args: argparse.Namespace
2531
+ ) -> dict[str, Any]:
2532
+ payload, destination, findings = linear_publication_input(args, recording=True)
2533
+ publications = payload["publications"]
2534
+ if not isinstance(publications, list):
2535
+ raise SystemExit("Linear publication results must be an array.")
2536
+ planned = {finding["findingId"]: finding["occurrenceId"] for finding in findings}
2537
+ current: dict[str, dict[str, str]] = {}
2538
+ external_ids: set[str] = set()
2539
+ for publication in publications:
2540
+ if (
2541
+ not isinstance(publication, dict)
2542
+ or not {"findingId", "occurrenceId", "issueIdentifier"}.issubset(publication)
2543
+ or not set(publication).issubset(
2544
+ {"findingId", "occurrenceId", "issueIdentifier", "url"}
2545
+ )
2546
+ or not isinstance(publication.get("findingId"), str)
2547
+ or not isinstance(publication.get("occurrenceId"), str)
2548
+ or not isinstance(publication.get("issueIdentifier"), str)
2549
+ or not publication["issueIdentifier"].strip()
2550
+ or (
2551
+ "url" in publication
2552
+ and (
2553
+ not isinstance(publication["url"], str)
2554
+ or not publication["url"].strip()
2555
+ )
2556
+ )
2557
+ ):
2558
+ raise SystemExit("Linear publication results contain an invalid issue association.")
2559
+ finding_id = publication["findingId"]
2560
+ issue_identifier = publication["issueIdentifier"]
2561
+ if planned.get(finding_id) != publication["occurrenceId"]:
2562
+ raise SystemExit(
2563
+ "A created Linear issue does not match its planned finding and occurrence."
2564
+ )
2565
+ if finding_id in current or issue_identifier in external_ids:
2566
+ raise SystemExit("Linear publication results repeat a finding or issue identifier.")
2567
+ current[finding_id] = publication
2568
+ external_ids.add(issue_identifier)
2569
+
2570
+ connection.execute("BEGIN IMMEDIATE")
2571
+ try:
2572
+ scan = verify_linear_publication_scan(connection, payload, findings)
2573
+ timestamp = now()
2574
+ for publication in publications:
2575
+ conflicting = connection.execute(
2576
+ """
2577
+ SELECT occurrence_id, external_url
2578
+ FROM finding_publications
2579
+ WHERE destination_type = ? AND team_id = ? AND project_id IS ?
2580
+ AND external_id = ?
2581
+ """,
2582
+ (
2583
+ destination["type"],
2584
+ destination["teamId"],
2585
+ destination.get("projectId"),
2586
+ publication["issueIdentifier"],
2587
+ ),
2588
+ ).fetchone()
2589
+ if conflicting is not None and conflicting["occurrence_id"] != publication[
2590
+ "occurrenceId"
2591
+ ]:
2592
+ raise SystemExit("This Linear issue is already associated with a different finding.")
2593
+ if (
2594
+ conflicting is not None
2595
+ and "url" in publication
2596
+ and conflicting["external_url"] != publication["url"]
2597
+ ):
2598
+ raise SystemExit("This Linear issue is already associated with a different URL.")
2599
+
2600
+ connection.execute(
2601
+ """
2602
+ INSERT INTO finding_publications (
2603
+ scan_id, finding_id, occurrence_id, destination_type,
2604
+ team_id, project_id, external_id, external_url, created_at
2605
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
2606
+ ON CONFLICT DO NOTHING
2607
+ """,
2608
+ (
2609
+ scan["id"],
2610
+ publication["findingId"],
2611
+ publication["occurrenceId"],
2612
+ destination["type"],
2613
+ destination["teamId"],
2614
+ destination.get("projectId"),
2615
+ publication["issueIdentifier"],
2616
+ publication.get("url"),
2617
+ timestamp,
2618
+ ),
2619
+ )
2620
+
2621
+ created = []
2622
+ for finding in findings:
2623
+ publication = current.get(finding["findingId"])
2624
+ if publication is None:
2625
+ continue
2626
+ row = connection.execute(
2627
+ """
2628
+ SELECT finding_id, occurrence_id, external_id, external_url
2629
+ FROM finding_publications
2630
+ WHERE scan_id = ? AND occurrence_id = ? AND destination_type = ?
2631
+ AND team_id = ? AND project_id IS ? AND external_id = ?
2632
+ """,
2633
+ (
2634
+ scan["id"],
2635
+ publication["occurrenceId"],
2636
+ destination["type"],
2637
+ destination["teamId"],
2638
+ destination.get("projectId"),
2639
+ publication["issueIdentifier"],
2640
+ ),
2641
+ ).fetchone()
2642
+ if row is None:
2643
+ raise SystemExit("A created Linear issue could not be read from scan history.")
2644
+ created.append(
2645
+ {
2646
+ "findingId": row["finding_id"],
2647
+ "occurrenceId": row["occurrence_id"],
2648
+ "issueIdentifier": row["external_id"],
2649
+ **({"url": row["external_url"]} if row["external_url"] is not None else {}),
2650
+ }
2651
+ )
2652
+ result = {"scanId": scan["id"], "destination": destination, "created": created}
2653
+ connection.commit()
2654
+ except BaseException:
2655
+ connection.rollback()
2656
+ raise
2657
+ return result
2658
+
2659
+
2406
2660
  def export_findings(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
2407
2661
  scan = require_scan(connection, args.scan_id)
2408
2662
  if scan["status"] != "complete":
@@ -3728,6 +3982,10 @@ def main() -> None:
3728
3982
  )
3729
3983
  elif args.command == "set-finding-remediation":
3730
3984
  result = set_finding_remediation(connection, args)
3985
+ elif args.command == "prepare-linear-publication":
3986
+ result = prepare_linear_publication(connection, args)
3987
+ elif args.command == "record-linear-publications":
3988
+ result = record_linear_publications(connection, args)
3731
3989
  elif args.command == "export-findings":
3732
3990
  result = export_findings(connection, args)
3733
3991
  elif args.command == "database-info":
@@ -55,6 +55,32 @@ def measured_scan_cost_json(usage: Mapping[str, Any]) -> str:
55
55
  return json.dumps({"usage": dict(usage)}, separators=(",", ":"), allow_nan=False)
56
56
 
57
57
 
58
+ def reconcile_completed_scan_cost(
59
+ connection: sqlite3.Connection,
60
+ scan: sqlite3.Row,
61
+ cost_json: str,
62
+ ) -> None:
63
+ """Persist authoritative SDK cost without discarding measured worker usage."""
64
+
65
+ existing = json.loads(scan["cost_json"]) if scan["cost_json"] is not None else {}
66
+ if isinstance(existing, dict) and "usage" in existing:
67
+ cost_json = json.dumps(
68
+ {**existing, "cost": json.loads(cost_json)},
69
+ separators=(",", ":"),
70
+ allow_nan=False,
71
+ )
72
+ connection.execute("BEGIN IMMEDIATE")
73
+ try:
74
+ connection.execute(
75
+ "UPDATE scans SET cost_json = ? WHERE id = ? AND status = 'complete'",
76
+ (cost_json, scan["id"]),
77
+ )
78
+ connection.commit()
79
+ except BaseException:
80
+ connection.rollback()
81
+ raise
82
+
83
+
58
84
  def collect_scan_usage(
59
85
  connection: sqlite3.Connection,
60
86
  scan: sqlite3.Row,
@@ -643,6 +643,46 @@ MIGRATIONS = (
643
643
  ADD COLUMN max_time_hours REAL NOT NULL DEFAULT 96;
644
644
  """,
645
645
  ),
646
+ (
647
+ 29,
648
+ "persist finding publication associations",
649
+ """
650
+ CREATE TABLE finding_publications (
651
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
652
+ scan_id TEXT NOT NULL REFERENCES scans(id) ON DELETE CASCADE,
653
+ finding_id TEXT NOT NULL REFERENCES findings(id),
654
+ occurrence_id TEXT NOT NULL
655
+ REFERENCES finding_occurrences(id) ON DELETE CASCADE,
656
+ destination_type TEXT NOT NULL,
657
+ team_id TEXT,
658
+ project_id TEXT,
659
+ external_id TEXT NOT NULL,
660
+ external_url TEXT,
661
+ created_at TEXT NOT NULL,
662
+ UNIQUE (occurrence_id, destination_type, team_id, project_id, external_id),
663
+ UNIQUE (destination_type, team_id, project_id, external_id)
664
+ );
665
+
666
+ CREATE INDEX finding_publications_by_scan
667
+ ON finding_publications(scan_id, occurrence_id, id);
668
+
669
+ CREATE INDEX finding_publications_by_finding
670
+ ON finding_publications(finding_id, id);
671
+ """,
672
+ ),
673
+ (
674
+ 30,
675
+ "preserve team-only finding publication associations",
676
+ """
677
+ CREATE UNIQUE INDEX finding_publications_team_only_occurrence
678
+ ON finding_publications(occurrence_id, destination_type, team_id, external_id)
679
+ WHERE project_id IS NULL;
680
+
681
+ CREATE UNIQUE INDEX finding_publications_team_only_external_issue
682
+ ON finding_publications(destination_type, team_id, external_id)
683
+ WHERE project_id IS NULL;
684
+ """,
685
+ ),
646
686
  )
647
687
 
648
688
 
package/dist/api.d.ts CHANGED
@@ -27,7 +27,7 @@ interface CodexClientLike {
27
27
  startThread(options: {
28
28
  workingDirectory: string;
29
29
  skipGitRepoCheck: boolean;
30
- approvalPolicy: "never";
30
+ approvalPolicy: "never" | "on-request";
31
31
  }): CodexThreadLike;
32
32
  }
33
33
  interface PreparedRuntime {