Codex Security Scans

CoWork OS ships a bundled Codex Security plugin pack for defensive repository security review. It adapts the Codex Security workflows into normal CoWork plugin-pack skills, slash commands, task timelines, approvals, workspace path rules, and packaged resources.

Access it from Settings > Customize > Codex Security, or invoke one of its slash commands in the composer:

/security-scan Run a security scan on this repository
/security-diff-scan Review this branch diff for security regressions
/deep-security-scan Run a deep repository-wide security scan

The pack is bundled at:

resources/plugin-packs/codex-security/

Packaged desktop/server builds include the whole pack under Electron resources as plugin-packs/codex-security.

Scan Modes

The top-level skills preserve the upstream Codex Security phase model:

1. Resolve scan target and artifact paths.
2. Generate deterministic worklists.
3. Build or reuse threat model context.
4. Run finding discovery.
5. Deduplicate candidate findings.
6. Validate plausible findings.
7. Run attack-path analysis where needed.
8. Render the final report.

Deep scans repeat the variance-sensitive discovery phase before centralized validation and final reporting.

Bundled Skills

The pack uses directory-backed skills via skillDirectories in cowork.plugin.json.

Directory-backed skills read SKILL.md and relative references/, scripts/, assets/, and agents/ files from their pack directory. CoWork uses the manifest definition first, then SKILL.md frontmatter, then a title generated from the skill ID for display metadata.

Skill Orchestration

Codex Security scan orchestration now lives in the bundled plugin-pack skills rather than hidden built-in tools. The /security-scan, /security-diff-scan, and /deep-security-scan entrypoints read their own SKILL.md instructions, references, and scripts from resources/plugin-packs/codex-security/.

The skill runtime uses normal workspace-scoped tools for reading, searching, command execution, file creation, sub-agent coordination, and report writing. There are no security_scan_* built-in tool handlers to call directly.

Artifact Layout

Scan skills should write artifacts under the active workspace by default:

<repo>/.cowork/security-scans/<repo-name>/<scan-id>/
├── artifacts/
│   ├── 01_context/
│   ├── 02_discovery/
│   │   ├── rank_input.csv
│   │   └── deep_review_input.csv
│   ├── 03_coverage/
│   ├── 04_reconciliation/
│   ├── 05_findings/
│   └── deep_discovery/
├── report.md
└── report.html

Deep-scan rounds add worker directories:

artifacts/deep_discovery/round-01/
├── worker-01/
├── worker-02/
├── worker-03/
├── worker-04/
├── worker-05/
└── worker-06/

Every deep-scan worker must produce:

threat_model.md
finding_discovery_report.md
seed_research.md
work_ledger.jsonl
raw_candidates.jsonl
dedupe_report.md
deduped_candidates.jsonl
repository_coverage_ledger.md

The JSONL files are parsed before a worker is considered usable. Malformed JSONL makes that worker unusable for the round merge.

Deep Scan Reconciliation

Deep Security Scan still expects six independent discovery workers per completed round. A round should not be treated as complete if:

• fewer or more than six worker-* directories exist
• any worker is missing a required artifact
• any worker has malformed JSONL in work_ledger.jsonl, raw_candidates.jsonl, or deduped_candidates.jsonl

When the skill reconciles completed worker output, it should write:

artifacts/deep_merge/round-XX_candidate_inventory.jsonl
artifacts/deep_merge/round-XX_candidate_inventory.md
artifacts/deep_merge/canonical_candidate_inventory.jsonl

Exact candidate keys are a bookkeeping aid only. The Codex Security skill still performs semantic remediation-subsumption merging before final validation and reporting.

Workspace Safety

Security scan workflows remain workspace-scoped:

• repo_root, artifact_root, scan_dir, and worker_dir should resolve inside the active workspace.
• artifact_root defaults to .cowork/security-scans/<repo-name> inside the target repository.
• scan_id may contain only letters, numbers, dot, underscore, or dash.
• scope for scoped-path scans must be a relative path inside the repository.
• Deep scans are repository-wide only. Use repository or scoped-path mode for narrower scans.

Imported third-party packs still use the normal imported-capability security gate. The bundled Codex Security pack is treated as first-party bundled content, packaged with the app, and loaded through normal plugin-pack discovery.

Validation Commands

Use these focused checks after changing Codex Security scan orchestration, the bundled pack manifest, or directory-backed skill loading:

npx vitest run src/electron/agent/tools/__tests__/registry-tool-catalog.test.ts src/electron/extensions/__tests__/codex-security-plugin-pack-manifest.test.ts
npm run build:electron

When changing skill content under resources/plugin-packs/codex-security/skills/, also run:

npm run skills:check:core
npm run skills:check

Implementation Landmarks

If this feature changes, update this guide, Plugin Packs, Security Guide, and Development in the same PR.