mirror of
https://github.com/openai/codex-security.git
synced 2026-11-22 17:19:20 +08:00
* docs(imports): correct scanner results and ticket intake checks * refactor(imports): reuse scanner severity mappings * feat(imports): publish selected Semgrep Guardian findings to Cloud * feat(cli): show readable imported findings in the terminal * docs(imports): explain scanner fields and source references --------- Co-authored-by: Michael D'Angelo <269034524+mldangelo-oai@users.noreply.github.com>
139 lines
5.1 KiB
Markdown
139 lines
5.1 KiB
Markdown
# Import GitHub code scanning findings
|
||
|
||
Use the JSON array from `codex-security import github`. It includes each
|
||
alert and the instance GitHub returned for the selected ref.
|
||
|
||
## Quick start
|
||
|
||
In the matching checkout, set the repository and source key. For GitHub Enterprise, export
|
||
`GH_HOST` with your hostname first. For a repeat import, use the exact source
|
||
key from your previous preview, including case.
|
||
|
||
```sh
|
||
repo=OWNER/REPO
|
||
source_key="${GH_HOST:-github.com}/$repo/code-scanning"
|
||
```
|
||
|
||
**Saved report.** Set `report=/private/path/alerts.json` if you already have
|
||
the collector's complete JSON array. Continue with [Preview the report](#preview-the-report).
|
||
|
||
### Export from GitHub
|
||
|
||
Sign in to the selected host with `gh auth login`.
|
||
A fine-grained token needs **Code scanning alerts: read**. A classic token
|
||
needs `security_events`, or `public_repo` for a public repository.
|
||
[GitHub API permissions](https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository)
|
||
|
||
The command below selects open alerts on the default branch. For a different
|
||
branch, add `--github-ref refs/heads/BRANCH` to the collector command. To
|
||
include fixed and dismissed alerts, add `--github-state all`. For exact
|
||
alerts across states, repeat `--github-alert NUMBER` and omit `--github-state`.
|
||
Save the complete array without output filters, token limits or `--full-output`.
|
||
Use a private temporary directory outside the checkout.
|
||
|
||
```sh
|
||
report=
|
||
out=$(mktemp -d) &&
|
||
codex-security import github "$repo" --format json > "$out/alerts.json" &&
|
||
report="$out/alerts.json"
|
||
```
|
||
|
||
### Preview the report
|
||
|
||
```sh
|
||
codex-security publish findings "$report" --to local --repository . \
|
||
--provider github --source-key "$source_key" --dry-run --format json
|
||
```
|
||
|
||
### Save and verify
|
||
|
||
Check the repository, ref and alert numbers against your selection. The alert
|
||
repository must match a comparable local Git remote when available, or the
|
||
selected Cloud repository. If the preview matches,
|
||
[save locally or publish to Cloud and verify the result](README.md#save-or-publish-and-verify).
|
||
|
||
## Identity and evidence
|
||
|
||
The host, repository, alert number and ref identify a finding. The same alert
|
||
on two refs keeps separate evidence. The finding URL opens the GitHub alert.
|
||
The file, line and commit come from the selected instance. Severity comes from
|
||
the rule’s security rating. A SARIF level such as `error` leaves a missing
|
||
security rating `unknown`.
|
||
|
||
A GitHub dismissal applies to the entire alert, even when a selected ref's
|
||
instance is open or fixed. A GitHub connection in Codex can select records.
|
||
The CLI collector authenticates separately with `gh`.
|
||
|
||
## Use the SDK
|
||
|
||
To collect with the SDK, use credentials from `gh` or supply `githubHost` and
|
||
a `githubToken` issued for that host. This example previews a Cloud import.
|
||
|
||
```ts
|
||
import {
|
||
importGitHubCodeScanningAlerts,
|
||
normalizeGitHubCodeScanningAlerts,
|
||
prepareNormalizedExternalPublication,
|
||
} from "@openai/codex-security";
|
||
|
||
const alerts = await importGitHubCodeScanningAlerts({
|
||
repository: "example/project",
|
||
});
|
||
const prepared = await prepareNormalizedExternalPublication(
|
||
normalizeGitHubCodeScanningAlerts(alerts, "cloud"),
|
||
{
|
||
provider: "github",
|
||
repository: "https://github.com/example/project",
|
||
sourceKey: "github.com/example/project/code-scanning",
|
||
},
|
||
);
|
||
console.log(prepared.preview);
|
||
```
|
||
|
||
After reviewing the Cloud preview, call `await prepared.publish()` to confirm.
|
||
If you supply normalized evidence that keeps the collector record in
|
||
`source_data`, imports check its original repository against the destination.
|
||
|
||
For local storage, call `normalizeGitHubCodeScanningAlerts(alerts, "local")` on
|
||
the original alerts to retain evidence that exceeds Cloud limits. Pass the result
|
||
to `prepareNormalizedLocalImport()` with `repository: "/path/to/project"`, inspect
|
||
its preview, and call `import()`. Alternatively, pass the saved alert file directly
|
||
to `prepareLocalExternalImport()`. Read records with `listLocalExternalFindings({ repository })`.
|
||
|
||
### Validate the selected alerts
|
||
|
||
To get a disposition per alert, validate the collected records against the matching checkout.
|
||
|
||
```ts
|
||
import {
|
||
CodexSecurity,
|
||
importGitHubCodeScanningAlerts,
|
||
} from "@openai/codex-security";
|
||
|
||
const findings = await importGitHubCodeScanningAlerts({
|
||
repository: "example/repository",
|
||
alertNumbers: [12, 18], // Omit for all open alerts on the default branch.
|
||
githubHost: "github.com",
|
||
githubToken: process.env["GH_TOKEN"],
|
||
});
|
||
|
||
const security = new CodexSecurity();
|
||
try {
|
||
for (const finding of findings) {
|
||
const result = await security.validate({
|
||
repositoryPath: "/path/to/repository",
|
||
finding,
|
||
});
|
||
console.log(finding.url, result.disposition, result.outputDir);
|
||
}
|
||
} finally {
|
||
await security.close();
|
||
}
|
||
```
|
||
|
||
SDK options include `state` (default `"open"`), `ref`, and `signal`.
|
||
Without `gh`, pass a `githubToken` issued for the selected `githubHost`.
|
||
If you omit the token, the SDK asks the GitHub CLI for credentials, including
|
||
its supported token environment variables. `githubHost` defaults to `GH_HOST` or `github.com`.
|
||
The token needs code-scanning read access; access failures reject the import.
|