Repository navigation
docs: clarify exposure triage evidence permissions and privacy - #261
Conversation
[skip-tests: documentation-only command example; CLI behavior unchanged]
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e38a13e7e4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ```bash | ||
| python3 -m exposuretriage.cli triage --input path/to/triage-bundle.json | ||
| cd plugins/vulnerability-management/exposure-triage-workbench | ||
| python3 -m exposuretriage.cli validate --input fixtures/bundles/synthetic-enterprise/bundle.json |
There was a problem hiding this comment.
When redaction accidentally removes a required collection or leaves another schema violation, this newly recommended validate command still reports success: ingest_triage_bundle() defaults missing advisories, assets, components, and reachability to empty lists and never evaluates triage-input.schema.json. A bundle containing only the schema version, bundle ID, and timestamp therefore validates and produces a zero-item report, so the workflow does not ensure that identifier links remain valid or that the demonstration is meaningful. Either perform actual schema/referential validation or explicitly document this command's narrower checks and direct analysts to a real validation gate.
AGENTS.md reference: plugins/AGENTS.md:L9-L13
Useful? React with 👍 / 👎.
|
|
||
| ### 2. Triage an Evidence Bundle via CLI | ||
|
|
||
| Before using real exports or sharing reports, follow the input access and private-evidence guidance in the [analyst playbook](docs/PLAYBOOK.md). |
There was a problem hiding this comment.
When users invoke the installed Codex plugin, .codex-plugin/plugin.json loads ./skills/ directly, and skills/exposure-triage/SKILL.md tells the agent to triage a real bundle to stdout or triage-report.json without mentioning authorization, restricted storage, log exposure, redaction, or file permissions. Those users need not traverse this README link, so the principal agent-facing workflow can still expose the private asset, owner, path, and reachability data this change is intended to protect; add the safeguards or a mandatory playbook reference before the skill's execution commands.
AGENTS.md reference: AGENTS.md:L110-L114
Useful? React with 👍 / 👎.
| 1. **Confirm Access and Protect Evidence**: | ||
| Obtain authorized, read-only access to the scoped advisory, asset inventory, component/SBOM, and reachability exports, plus local read access to the assembled JSON bundle. The offline triage command does not need cloud administrator, network probe, or source-system write permissions. Exporting the source data may require separate permissions; follow the source system's approval process. If writing a report, use an approved directory where you have write access. | ||
|
|
||
| Treat both the bundle and its reports as private evidence. They can contain asset and subscription IDs, display names, owners, software paths, tags, and free-text reachability evidence. Keep them in an approved, access-restricted workspace and follow the engagement's retention rules. The CLI does not redact fields or set restrictive file permissions; set a restrictive shell `umask` (for example, `umask 077`) before creating reports. Without `--output`, the report goes to standard output and may be captured in terminal transcripts or CI logs. |
There was a problem hiding this comment.
When an analyst reruns triage using an existing report path, umask 077 provides no protection because Path.write_text() truncates the existing inode without changing its mode; an existing 0644 report remains 0644 after following this guidance. Reusing an output filename is normal for iterative triage, so private evidence can remain readable beyond the intended audience despite the documented precaution; require a new destination or instruct operators to set and verify the output mode explicitly.
AGENTS.md reference: AGENTS.md:L101-L108
Useful? React with 👍 / 👎.
1 participant
Summary
Clarify the permissions and handling required for exposure-triage evidence in the analyst playbook, and link that guidance from the package quick start. The playbook now distinguishes read-only access for the offline triage command from permissions needed to export source data or write a report. It describes private fields, restricted storage, redaction, and a synthetic example that can safely be displayed.
Addresses #195.
Acceptance criteria
make check; update affected docs.Evidence
python3.12 -m exposuretriage.cli validate --input fixtures/bundles/synthetic-enterprise/bundle.jsonaccepted the synthetic bundle;python3.12 -m exposuretriage.cli triage --input fixtures/bundles/synthetic-enterprise/bundle.jsonproduced the expected seven-item synthetic report;python3.12 scripts/validate_package.pypassed;git diff --checkpassed.make checkpassed in this checkout with a Python 3.14 test environment selected throughPATHandPYTHON. The system Python 3.9 did not meet the repository's Python 3.11 minimum. The full run passed after using the supported environment and allowing the test suite's local Unix socket bind.gitleakswith no findings.Impact review
umask; a Git revert restores the prior guidance. No deployment or data migration is involved.Risks and residual uncertainty
The CLI does not enforce redaction or restrictive file permissions; the new guidance requires operators to handle those controls. Human review of this exact head commit and hosted CI are pending, so this PR remains draft.