Skip to content
Big Picture

Verifying Artifacts

This workflow covers verifying artifacts for integrity, authenticity, and safety before publishing releases. Verification ensures artifacts are not corrupted, tampered with, or contain security threats.

Prerequisites

Section titled “Prerequisites”
  • API credentials with artifact management permissions
  • Artifacts ready for verification
  • SHA-256 hash computed for each artifact
  • Code signing certificates (if required by platform)

Understanding Verification Stages

Section titled “Understanding Verification Stages”

Artifact verification includes four stages:

  1. Hash verification — Verify artifact integrity using SHA-256
  2. Signature verification — Verify code signing signatures (platform-specific)
  3. Malware scanning — Scan for security threats
  4. Structure validation — Validate artifact structure and metadata

Step 1: Compute Hash

Section titled “Step 1: Compute Hash”

Compute SHA-256 hash before uploading:

Terminal window
# Linux/macOS
sha256sum installer.msi


# Windows (PowerShell)
Get-FileHash installer.msi -Algorithm SHA256

Save the hash—you’ll need it when registering the artifact.

Step 2: Verify Code Signature

Section titled “Step 2: Verify Code Signature”

Verify code signature matches platform requirements:

Windows (Authenticode):

Terminal window
signtool verify /pa installer.msi

macOS (Code signature):

Terminal window
codesign --verify --deep --strict installer.dmg

Linux (GPG, if applicable):

Terminal window
gpg --verify installer.deb.asc installer.deb

Step 3: Register Artifact

Section titled “Step 3: Register Artifact”

Register the artifact with Big Picture. Verification occurs during registration:

Terminal window
curl -X POST "${BP_BASE_URL}/v1/artifacts" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "EXTERNAL",
    "sha256": "a1b2c3d4e5f6...",
    "size_bytes": 15728640,
    "external_url": "https://artifacts.example.com/releases/v1.0.0/installer.msi"
  }'

Big Picture verifies:

  • Hash matches provided SHA-256
  • Signature is valid (if required)
  • Structure is valid

Step 4: Check Verification Status

Section titled “Step 4: Check Verification Status”

Query verification status:

Terminal window
curl "${BP_BASE_URL}/v1/artifacts/art_abc123/verification" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "artifact_id": "art_abc123",
  "verification_status": "verified",
  "verified_at": "2024-01-15T10:40:00Z",
  "hash_verification": {
    "status": "passed",
    "sha256": "a1b2c3d4e5f6...",
    "verified_at": "2024-01-15T10:30:00Z"
  },
  "signature_verification": {
    "status": "passed",
    "signer": "Example Corp",
    "certificate_thumbprint": "abc123...",
    "verified_at": "2024-01-15T10:31:00Z"
  },
  "malware_scan": {
    "status": "clean",
    "scanner": "virustotal",
    "scanned_at": "2024-01-15T10:35:00Z",
    "threats_detected": 0
  },
  "structure_validation": {
    "status": "passed",
    "validated_at": "2024-01-15T10:36:00Z"
  }
}

Step 5: Re-verify Artifact (If Needed)

Section titled “Step 5: Re-verify Artifact (If Needed)”

Re-verify an existing artifact:

Terminal window
curl -X POST "${BP_BASE_URL}/v1/artifacts/art_abc123/verify" \
  -H "Authorization: Bearer $BP_API_TOKEN"

This triggers a new verification cycle.

Platform-Specific Requirements

Section titled “Platform-Specific Requirements”

Windows:

  • Authenticode signature required for MSI/EXE
  • Certificate must be valid and not expired
  • Certificate chain must verify to trusted root

macOS:

  • Code signature required for DMG/PKG
  • Notarization recommended
  • Certificate must be valid

Linux:

  • GPG signature recommended for DEB/RPM
  • Signature verification optional but recommended

Handling Verification Failures

Section titled “Handling Verification Failures”

Hash mismatch:

  • Re-compute hash and verify it matches
  • Re-upload artifact if using managed storage
  • Check for corruption during transfer

Signature failure:

  • Verify certificate is valid and not expired
  • Check certificate chain is complete
  • Re-sign artifact if needed

Malware detected:

  • Review scan results for false positives
  • Investigate threats before proceeding
  • Remove threats and re-scan

Structure validation failure:

  • Verify artifact format is correct
  • Check for corruption
  • Rebuild artifact if needed

CI/CD Integration

Section titled “CI/CD Integration”

Integrate verification into your CI/CD pipeline:

# Example GitHub Actions workflow
- name: Compute Hash
  id: hash
  run: |
    SHA256=$(sha256sum ${{ inputs.artifact_path }} | cut -d' ' -f1)
    echo "hash=$SHA256" >> $GITHUB_OUTPUT


- name: Verify Signature
  run: |
    signtool verify /pa ${{ inputs.artifact_path }}


- name: Register Artifact
  run: |
    curl -X POST "${BP_BASE_URL}/v1/artifacts" \
      -H "Authorization: Bearer ${{ secrets.BP_API_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d "{
        \"source_type\": \"EXTERNAL\",
        \"sha256\": \"${{ steps.hash.outputs.hash }}\",
        \"size_bytes\": $(stat -f%z ${{ inputs.artifact_path }}),
        \"external_url\": \"$ARTIFACT_URL\"
      }"

Best Practices

Section titled “Best Practices”

Verify before publishing: Always verify artifacts before creating releases.

Automate verification: Integrate verification into CI/CD pipelines.

Monitor verification status: Check verification status regularly.

Handle failures promptly: Address verification failures before publishing.

Document decisions: Document any manual review decisions for audit purposes.

Next Steps

Section titled “Next Steps”