Assess software supply-chain risk

Supply-chain analysis examines provenance, integrity, publisher trust, registry metadata, and typosquatting. SCA/SBOM covers component inventory and known vulnerabilities. The security owner reviews both reports before a release decision.

Use the findings when updating dependencies and preparing a release. Locate the package or lockfile, review the reason for each finding, and assign a correction. The saved report ties the decision to the checkout that was analyzed.

How the analysis works

The trust report’s maintainers and scorecard fields show the data used in the assessment. The registry’s ecosystem field selects the popular-package catalog for automatic name comparison. The current CLI returns unknown for dependencies from requirements.txt, package.json, and package-lock.json. In that case, review the name and publisher manually in the package manager’s registry for the source manifest.

In the JSON report, the top-level risk_level is calculated from the findings array. The value in components[].risk_level is calculated from the individual component’s trust score. For example, an empty findings array gives an overall level of minimal, while a component score of 5.0 maps to medium. A null value in checksum_match or lockfile_consistent means that the comparison was not performed. When reviewing the report, match these fields to the component data and finding reason.

Prepare the scan

Install the CLI using the CLI guide. Run these PowerShell examples from the CodeGraph repository root. Select the directory containing source and dependency manifests:

$env:CODEGRAPH_ALLOW_LOCAL_PYTHON_CLI = '1'
$sourcePath = 'C:/projects/my-project'
if (-not (Test-Path -LiteralPath $sourcePath -PathType Container)) { throw 'Source directory missing' }

Replace $sourcePath with your source directory. --path takes precedence over --project. Without an explicit path, an unresolved project name or lookup error falls back to the current directory .. Use an explicit path for a reproducible run.

Run the scan

python -m src.cli supply-chain scan `
  --path "$sourcePath" `
  --format sarif `
  --fail-on high `
  --output 'supply-chain.sarif'
$scanExit = $LASTEXITCODE

Confirm the project revision and network/cache freshness. Use a score or severity as a triage signal, then record the accountable security or release decision.

The report is written in the current directory and overwrites a file with the same name. Exit code 0 means no findings meet the configured threshold; 1 means a high or critical finding with --fail-on high; 2 indicates a dependency-scan or supply-chain analysis error. Check $scanExit, the report, and error messages together: an existing file can belong to an earlier run. Without --fail-on, findings alone do not change exit code 0.

Example: find and remove a build-script pattern

Create a separate demonstration directory to check the build-script analysis stage. It has no dependencies: empty requirements.txt and poetry.lock files keep the example focused on setup.py. CodeGraph reads this file and searches for patterns; the scan does not execute the build script.

Run these commands in the same PowerShell session from the CodeGraph root:

$demoPath = Join-Path ([System.IO.Path]::GetTempPath()) ('codegraph-supply-demo-' + [guid]::NewGuid().ToString('N'))
New-Item -ItemType Directory -Path $demoPath | Out-Null
Set-Content -LiteralPath (Join-Path $demoPath 'requirements.txt') -Value '' -Encoding UTF8
Set-Content -LiteralPath (Join-Path $demoPath 'poetry.lock') -Value '' -Encoding UTF8
Set-Content -LiteralPath (Join-Path $demoPath 'setup.py') -Value "eval('1 + 1')" -Encoding UTF8
$beforePath = Join-Path $demoPath 'before.json'
python -m src.cli supply-chain scan --path "$demoPath" --format json --fail-on high --output "$beforePath"
$beforeExit = $LASTEXITCODE
$before = Get-Content -LiteralPath $beforePath -Raw | ConvertFrom-Json
$before.findings | Select-Object finding_type, severity, component_name, evidence
if ($beforeExit -ne 1 -or @($before.findings).Count -ne 1) { throw 'Expected one high finding' }

The report contains one finding: finding_type is suspicious_pattern, severity is high, component_name is setup.py, and evidence includes line:1. The exit code is 1. The detector identifies the eval call as dynamic code execution. When reviewing a real project, inspect the purpose of the call and its inputs.

Remove the dynamic evaluation from the demonstration file and scan again:

Set-Content -LiteralPath (Join-Path $demoPath 'setup.py') -Value '# Reviewed build script: no dynamic evaluation' -Encoding UTF8
$afterPath = Join-Path $demoPath 'after.json'
python -m src.cli supply-chain scan --path "$demoPath" --format json --fail-on high --output "$afterPath"
$afterExit = $LASTEXITCODE
$after = Get-Content -LiteralPath $afterPath -Raw | ConvertFrom-Json
if ($afterExit -ne 0 -or @($after.findings).Count -ne 0) { throw 'Expected no findings after correction' }

The second scan returns 0 and an empty findings array. Compare before.json and after.json: they retain the results before and after the change. Both reports have total_components: 0 because the example checks a script without dependencies. To analyze components, use your project directory from the previous section.

Focused checks

python -m src.cli supply-chain trust --path "$sourcePath" --format json
python -m src.cli supply-chain typosquatting --path "$sourcePath"

Use supply-chain registry to inspect the component registry and gost-report only when the GOST assessment is in scope. Check exact subcommand help for the installed release. The GOST report groups the findings for a subsequent requirements review.

Use the CLI or MCP tools below for provenance and trust checks. The project-scoped SCA API provides component inventory and vulnerability analysis, as described in the SCA/SBOM guide.

Work through MCP

Select an MCP profile for security review using the operator guide, then set project to the project name. Use codex:role:codegraph_appsec:mutation for the full report and codex:role:codegraph_appsec:read for the trust report. The tools get the source directory from the project configuration. An empty name selects the MCP server’s current working directory.

Review each finding

1. Locate the component or script using its name and evidence. For a dependency, verify its version, registry, publisher, and artifact digest.
2. Review the reason for the finding: name similarity, a hash comparison, a trust-score factor, or a script line.
3. Choose an action: collect publisher information, replace a package, update the lockfile, or change the script.
4. Record the decision, owner, and deadline in the release task. Attach the report and project revision.
5. Scan again after the change and compare the result with the original report.

Reference material

For component inventory and vulnerability analysis, see SCA and SBOM.