Software Supply Chain Security - HW1

Description

This project implements a Python-based verification system for Sigstore's Rekor transparency log. It demonstrates software supply chain security concepts including artifact signing, signature verification, and transparency log consistency validation.

Student NetID: tu2090

Features

• Sign artifacts using cosign with ephemeral certificates
• Verify signatures from Rekor transparency log entries
• Validate Merkle tree inclusion proofs (RFC 6962)
• Verify log consistency between checkpoints
• Command-line interface for all verification operations

Project Structure

.
├── main.py                      # Main verification script with CLI
├── util.py                      # Cryptographic utility functions
├── merkle_proof.py              # Merkle tree proof verification (RFC 6962)
├── artifact.md                  # Sample signed artifact
├── artifact.bundle              # Cosign signature bundle
├── my_checkpoint.json           # Saved Rekor checkpoint
├── tests/                       # Test suite
│   ├── __init__.py
│   ├── test.py                  # Core functionality tests
│   └── test_checkpoint.py       # CLI checkpoint tests
├── pyproject.toml               # Poetry dependency configuration
├── poetry.lock                  # Locked dependencies
├── .pre-commit-config.yaml      # Pre-commit hooks (TruffleHog)
├── README.md                    # This file
├── SECURITY.md                  # Security policy
├── CONTRIBUTING.md              # Contribution guidelines
├── LICENSE                      # MIT License
└── CODEOWNERS                   # Code ownership

Installation

Prerequisites

• Python 3.10 or higher
• pip or Poetry package manager
• cosign (Sigstore signing tool)
• rekor-cli (Rekor command-line interface)

Install System Dependencies (macOS)

# Install cosign
brew install cosign

# Install rekor-cli
brew install rekor-cli

# Verify installations
cosign version
rekor-cli version

Install Python Dependencies

Using Poetry (Recommended)

# Install Poetry if not already installed
curl -sSL https://install.python-poetry.org | python3 -

# Install project dependencies
poetry install

# Activate virtual environment
poetry shell

Using pip

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On macOS/Linux

# Install dependencies
pip install requests cryptography
pip install pytest pytest-cov  # For testing

Usage

1. Sign an Artifact

# Sign artifact with cosign (requires identity verification)
cosign sign-blob ./artifact.md --bundle artifact.bundle

This will:

• Open browser for identity verification (GitHub/Google/Microsoft)
• Generate ephemeral certificate
• Sign the artifact
• Store signature in artifact.bundle

2. Get Current Checkpoint

# Fetch latest Rekor checkpoint
python main.py -c

# With debug mode (saves to checkpoint.json)
python main.py -d -c

3. Verify Inclusion Proof

# Verify artifact signature and inclusion in Rekor log
python main.py --inclusion LOG_INDEX --artifact artifact.md

# With debug output
python main.py -d --inclusion LOG_INDEX --artifact artifact.md

This verifies:

• Artifact signature is valid
• Certificate used for signing
• Entry is included in Merkle tree

4. Verify Consistency Proof

# Verify log consistency between two checkpoints
python main.py --consistency \
  --tree-id TREE_ID \
  --tree-size OLD_SIZE \
  --root-hash OLD_ROOT_HASH

### Command-Line Options

usage: main.py [-h] [-d] [-c] [--inclusion LOG_INDEX] [--artifact FILEPATH] [--consistency] [--tree-id TREE_ID] [--tree-size SIZE] [--root-hash HASH]

options: -h, --help Show help message -d, --debug Enable debug mode with verbose output -c, --checkpoint Fetch and display latest checkpoint --inclusion INDEX Verify inclusion proof for log index --artifact PATH Artifact file path for signature verification --consistency Verify consistency between checkpoints --tree-id ID Previous checkpoint tree ID --tree-size SIZE Previous checkpoint tree size --root-hash HASH Previous checkpoint root hash

## Testing

### Run Tests
```bash
# Run all tests
pytest

# Run with verbose output
pytest -v

# Run with coverage report
pytest --cov=. --cov-report=term-missing

# Run specific test file
pytest tests/test.py

# Generate HTML coverage report
pytest --cov=. --cov-report=html
open htmlcov/index.html  # View in browser

Test Coverage

Current test coverage: >75%

Test files:

• tests/test.py - Core functionality tests
• tests/test_checkpoint.py - CLI checkpoint tests

Code Modules

main.py

Main script containing:

• get_log_entry() - Fetch log entry by index
• get_verification_proof() - Fetch entry with inclusion proof
• get_latest_checkpoint() - Fetch current checkpoint
• inclusion() - Verify inclusion proof
• consistency() - Verify consistency proof
• main() - CLI argument parser

util.py

Cryptographic utilities:

• extract_public_key() - Extract public key from X.509 certificate
• verify_artifact_signature() - Verify ECDSA signature using public key

merkle_proof.py

Merkle tree verification (RFC 6962):

• Hasher - SHA256 hasher with domain separation
• verify_inclusion() - Verify Merkle inclusion proof
• verify_consistency() - Verify Merkle consistency proof
• compute_leaf_hash() - Compute RFC 6962 leaf hash

Development

Pre-commit Hooks

This project uses pre-commit hooks for secret detection:

# Install pre-commit hooks
pre-commit install

# Run manually on all files
pre-commit run --all-files

The .pre-commit-config.yaml configures TruffleHog to scan for secrets before each commit.

Code Quality Tools

Configured in pyproject.toml:

• black - Code formatting (line length: 100)
• ruff - Linting
• mypy - Type checking
• flake8 - Style guide enforcement
• pylint - Code analysis
• bandit - Security linting

Run code quality checks:

black .
ruff check .
mypy .

Dependencies

Runtime Dependencies

• requests (^2.31.0) - HTTP library for Rekor API calls
• cryptography (^42.0.0) - X.509 certificate handling and signature verification
• PyJWT (^2.8.0) - JSON Web Token operations

Development Dependencies

• pytest (^7.4.3) - Testing framework
• pytest-cov (^4.1.0) - Coverage reporting
• mypy (^1.8.0) - Static type checker
• black (^23.12.0) - Code formatter
• ruff (^0.1.9) - Fast Python linter
• flake8 (^7.0.0) - Style checker
• pylint (^3.0.3) - Code analyzer
• bandit (^1.7.6) - Security checker

Architecture

Verification Flow

1. Sign Artifact (cosign)
   └─> Creates artifact.bundle with signature + certificate

2. Inclusion Verification
   ├─> Fetch log entry from Rekor
   ├─> Extract signature and certificate
   ├─> Verify artifact signature locally
   ├─> Compute leaf hash (RFC 6962)
   └─> Verify Merkle inclusion proof

3. Consistency Verification
   ├─> Fetch previous checkpoint
   ├─> Fetch latest checkpoint
   ├─> Request consistency proof from Rekor
   └─> Verify Merkle consistency proof

Rekor API Endpoints Used

• GET /api/v1/log - Get latest checkpoint
• GET /api/v1/log/entries?logIndex=N - Get log entry
• GET /api/v1/log/entries?logIndex=N&proof=true - Get entry with proof
• GET /api/v1/log/proof?firstSize=N&lastSize=M - Get consistency proof

Security

See SECURITY.md for:

• Vulnerability reporting process
• Supported versions
• Security best practices

Contributing

See CONTRIBUTING.md for:

• Code of conduct
• Pull request process
• Code style guidelines
• Testing requirements

License

This project is licensed under the MIT License - see the LICENSE file for details.

Assignment Information

Course: Software Supply Chain Security - Fall 2025
Student NetID: tu2090
Assignment: Assignments

Acknowledgments

• Based on Sigstore tooling (rekor-cli, rekor-monitor)
• Template inspiration from python-rekor-monitor-template
• RFC 6962: Certificate Transparency
• Sigstore Project: https://www.sigstore.dev/

Resources

• Sigstore Documentation
• Rekor API Specification
• Cosign Documentation

Troubleshooting

Common Issues

Issue: ModuleNotFoundError: No module named 'requests'
Solution: Install dependencies with poetry install or pip install requests cryptography

Issue: Signature verification fails
Solution: Ensure artifact.md hasn't been modified since signing

Issue: Inclusion proof verification fails
Solution: Verify you're using the correct log index from artifact.bundle

Issue: Pre-commit hook blocks commit
Solution: Secret detected - remove sensitive data before committing

Contact

For questions or issues related to this assignment:

• Check SECURITY.md for security concerns
• See CONTRIBUTING.md for contribution guidelines
• Review course materials and assignment documentation