Supply Chain Security

CodeGraph provides supply chain security analysis as part of GOST R 56939-2024 process 5.17. The module evaluates third-party component trust, detects typosquatting, verifies dependency integrity, and generates audit-ready GOST reports.

Overview¶

Supply chain security differs from SCA (Software Composition Analysis). While SCA answers “Are there known CVEs in dependencies?”, supply chain analysis answers “Can we trust the suppliers and their delivery channels?”

CodeGraph’s supply chain module provides:

Component Registry — catalogs all direct, transitive, and dev dependencies with ecosystem metadata
Trust Scoring — composite trust assessment (0-10) using OpenSSF Scorecard, maintainer count, activity, security policy, and popularity
Typosquatting Detection — Levenshtein distance analysis against popular package databases
Integrity Verification — checksum and lockfile consistency checks
Malicious Code Detection — pattern scanning of post-install scripts
GOST 5.17.3 Reports — audit-ready artifacts for Russian regulatory compliance

Architecture¶

Dependencies (SCA)  ──►  Component Registry
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        Trust Scorer    Integrity       Malicious Code
        (OpenSSF +      Checker         Detector
         metadata)      (checksums,     (typosquatting,
                         lockfiles)      patterns)
              │               │               │
              └───────────────┼───────────────┘
                              ▼
                     SupplyChainReport
                     (JSON / Markdown / SARIF / GOST)

CLI Commands¶

Full Scan¶

python -m src.cli supply-chain scan \
    [--project NAME] \
    [--path /path/to/source] \
    [--format json|markdown|sarif|gost] \
    [--language en|ru] \
    [--output report.md] \
    [--fail-on critical|high|medium]

Exit codes: - 0 — no findings above the --fail-on threshold - 1 — findings above threshold detected - 2 — execution error

Component Registry¶

python -m src.cli supply-chain registry \
    [--project NAME] \
    [--format json|markdown]

Lists all components with type (direct/transitive/dev), ecosystem, registry URL, and license.

Trust Scores¶

python -m src.cli supply-chain trust \
    [--project NAME] \
    [--min-score 5.0] \
    [--format json|markdown]

When --min-score is specified, only components below the threshold are shown.

Typosquatting Detection¶

python -m src.cli supply-chain typosquatting [--project NAME]

Checks package names against a database of popular packages using Levenshtein distance.

GOST 5.17.3 Report¶

python -m src.cli supply-chain gost-report \
    [--project NAME] \
    [--language ru|en] \
    [--output gost_sc_report.md]

Generates a report with sections 5.17.3.1 (supplier components), 5.17.3.3 (critical elements), 5.17.3.4 (integrity results), and 5.17.3.5 (scan results).

REST API¶

Method	Endpoint	Description
POST	`/api/v1/supply-chain/scan`	Full supply chain scan
GET	`/api/v1/supply-chain/registry`	Component registry
GET	`/api/v1/supply-chain/trust`	Trust scores
GET	`/api/v1/supply-chain/findings`	Security findings
GET	`/api/v1/supply-chain/gost-report`	GOST 5.17.3 report

POST /scan¶

Request:

{
  "fail_on": "critical",
  "include_trust": true
}

Response:

{
  "project": "myapp",
  "timestamp": "2026-03-10T12:00:00",
  "risk_level": "low",
  "total_components": 45,
  "direct_components": 12,
  "transitive_components": 33,
  "avg_trust_score": 7.2,
  "findings_count": 2,
  "findings": [...],
  "components": [...]
}

GET /trust¶

Query parameters: - min_score (float) — show only components below this score

GET /gost-report¶

Query parameters: - language — ru (default) or en

MCP Tools¶

Tool	Description
`codegraph_supply_chain_scan`	Full supply chain security scan
`codegraph_supply_chain_trust`	Trust score assessment

codegraph_supply_chain_scan¶

Parameters: - format — json, markdown, sarif, gost (default: json) - fail_on — severity threshold (empty = no threshold) - language — ru or en - project — project name (optional)

codegraph_supply_chain_trust¶

Parameters: - min_score — show only components below threshold (0 = all) - project — project name (optional)

Trust Scoring¶

Trust score is a weighted composite of 6 factors:

Factor	Weight	Scale	Description
OpenSSF Scorecard	0.40	0-10	Automated security assessment
Maintainer count	0.15	0-10	3+ maintainers = max score
Freshness	0.15	0-10	Days since last release (180+ = 0)
Security policy	0.10	0/10	SECURITY.md present
Popularity	0.10	0-10	Logarithmic star count
Signed releases	0.10	3/10	GPG/Sigstore signed

Risk levels mapped from score:

Score	Risk Level
0-2.0	CRITICAL
2.1-4.0	HIGH
4.1-6.0	MEDIUM
6.1-8.0	LOW
8.1-10.0	MINIMAL

Finding Types¶

Type	Severity	Description
`typosquatting`	high	Package name similar to a popular package
`suspicious_script`	critical	Suspicious npm lifecycle script
`suspicious_pattern`	high	Suspicious pattern in build scripts
`no_lockfile`	medium	Missing lockfile for manifest
`lockfile_mismatch`	high	Version mismatch in lockfile
`checksum_mismatch`	critical	Checksum verification failed
`low_trust`	medium/low	Trust score below threshold
`abandoned_package`	medium	No release for 730+ days
`single_maintainer`	low	Bus factor = 1
`no_security_policy`	low	No SECURITY.md
`av_detection`	high	Antivirus detection (reserved, v2)

Signature Verification¶

IntegrityChecker performs ecosystem-specific signature and hash verification for each component during the scan pipeline:

Ecosystem	Method	Source
pypi	`pip-hash`	`--hash=sha256:...` in `requirements.txt`
npm	`npm-integrity`	`integrity` field in `package-lock.json`
go	`go-sum`	Hash entries in `go.sum`
crates.io	`cargo-checksum`	`checksum` field in `Cargo.lock`
sigstore	`cosign verify-blob`	Sigstore/cosign (if installed)

Installed hash resolution:

Ecosystem	Method
pypi	`importlib.metadata` RECORD file (SHA256)
npm	`integrity` from `package-lock.json`
go	Hash from `go.sum`

The IntegrityResult.signature_valid field is populated for each component: - True — ecosystem-specific hash or signature found and valid - False — signature verification failed - None — no signature data available for this ecosystem

Sigstore/cosign support is available for artifact-level verification. Requires cosign on PATH; availability is cached per session.

Configuration¶

# config.yaml
supply_chain:
  enabled: true
  trust:
    scorecard:
      enabled: true
      timeout: 30
    thresholds:
      low_trust: 3.0
      abandoned_days: 730
  typosquatting:
    enabled: true
    max_distance: 2
    popular_packages_path: null
  integrity:
    check_checksums: true
    check_lockfiles: true
  signatures:
    verify_pip: true
    verify_npm: true
    verify_go: true
    verify_cargo: true
    cosign_enabled: false
  detector:
    scan_post_install: true
  ci:
    fail_on: "high"

CI Integration¶

GitHub Actions¶

- name: Supply Chain Check
  run: |
    python -m src.cli supply-chain scan \
      --format sarif \
      --fail-on high \
      --output supply-chain.sarif

GitLab CI¶

supply-chain:
  script:
    - python -m src.cli supply-chain scan --fail-on high --format json
  allow_failure: false

Module Structure¶

src/supply_chain/
    __init__.py          — exports
    models.py            — ComponentType, RiskLevel, FindingType, TrustScore,
                           SupplyChainComponent, IntegrityResult, SCFinding,
                           SupplyChainReport
    registry.py          — ComponentRegistry (DependencyGraph → components)
    scorecard.py         — ScorecardClient (OpenSSF Scorecard API)
    trust_scorer.py      — TrustScorer (6-factor weighted average)
    typosquatting.py     — TyposquattingDetector (Levenshtein + popular DBs)
    integrity.py         — IntegrityChecker (8 lockfile parsers, checksums, signature integration)
    signature.py         — SignatureVerifier (pip-hash, npm-integrity, go-sum, cargo, cosign)
    detector.py          — MaliciousCodeDetector (10+ patterns, npm hooks)
    report.py            — SupplyChainReportRenderer (JSON, Markdown, SARIF)
    gost_report.py       — SupplyChainGostReport (GOST 5.17.3 sections)
    scanner.py           — SupplyChainScanner (orchestrator)

SCA / SBOM — composition analysis (prerequisite)
Release Gate — consumes supply chain findings
GOST Compliance — overall compliance mapping