Forensic Usage Guidelines

Overview

Jenkins Credential Decryptor is designed for forensically sound credential recovery from Jenkins infrastructure. This document provides guidelines for evidence preservation, chain of custody considerations, and proper documentation during security assessments and incident response.

Evidence Preservation

Read-Only Operations

The tool operates in read-only mode by default to prevent evidence contamination:

No file modification: Original Jenkins files are never modified during decryption
No log injection: Tool does not write to Jenkins logs or configuration files
Memory-only processing: Decryption occurs in memory without intermediate file writes
Explicit output: Exports only occur when explicitly requested via --export-json or --export-csv

File Integrity Verification

Generate and preserve cryptographic hashes of source files before processing:

# Linux/macOS
sha256sum master.key > evidence_hashes.txt
sha256sum hudson.util.Secret >> evidence_hashes.txt
sha256sum credentials.xml >> evidence_hashes.txt

# Windows PowerShell
Get-FileHash master.key -Algorithm SHA256 >> evidence_hashes.txt
Get-FileHash hudson.util.Secret -Algorithm SHA256 >> evidence_hashes.txt
Get-FileHash credentials.xml -Algorithm SHA256 >> evidence_hashes.txt

Verify hashes after extraction and before processing to detect tampering:

# Linux/macOS
sha256sum -c evidence_hashes.txt

# Windows PowerShell
# Manual verification against recorded hashes

Timestamp Preservation

Preserve original file modification times during extraction:

# Linux/macOS - preserve timestamps during copy
cp -p /var/jenkins_home/secrets/master.key ./evidence/

# Windows - preserve metadata
Copy-Item -Path "C:\Jenkins\secrets\master.key" -Destination ".\evidence\" -Force

# Docker extraction with metadata
docker cp jenkins:/var/jenkins_home/secrets/master.key ./evidence/
stat ./evidence/master.key  # Record original timestamps

Record timestamps in forensic notes:

File: master.key
Original Location: /var/jenkins_home/secrets/master.key
Extracted: 2026-01-19 07:00:00 UTC
Modified: 2025-08-15 14:32:18 UTC
Accessed: 2026-01-18 22:10:05 UTC
SHA256: 4a3f2b1c8d9e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a

Chain of Custody

Evidence Documentation

Maintain comprehensive chain of custody documentation:

Required Information:

Source system identification (hostname, IP address, Jenkins version)
Extraction timestamp (UTC)
Extracted file paths
Cryptographic hashes (SHA256)
Extraction method (SSH, Docker, file copy)
Operator identity
Storage location
Access log

Example Evidence Log:

Case: SEC-2026-001-JENKINS
Date: 2026-01-19
Operator: J. Smith
Source: jenkins-prod-01.company.com (10.20.30.40)
Jenkins Version: 2.426.1

Files Extracted:
1. /var/jenkins_home/secrets/master.key
   - Extracted: 2026-01-19 07:15:23 UTC
   - Method: SSH/SCP via incident response account
   - SHA256: 4a3f2b1c8d9e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a
   - Size: 32 bytes

2. /var/jenkins_home/secrets/hudson.util.Secret
   - Extracted: 2026-01-19 07:15:25 UTC
   - Method: SSH/SCP via incident response account
   - SHA256: 8f7e6d5c4b3a2918f7e6d5c4b3a2918f7e6d5c4b3a2918f7e6d5c4b3a2918f7e
   - Size: 256 bytes

3. /var/jenkins_home/credentials.xml
   - Extracted: 2026-01-19 07:15:28 UTC
   - Method: SSH/SCP via incident response account
   - SHA256: 2d4e6f8a0c2e4f6a8b0d2e4f6a8c0e2f4a6b8d0e2f4a6c8e0d2f4a6b8c0e2f4
   - Size: 4,512 bytes

Storage: Network forensic share (\\forensics\cases\SEC-2026-001)
Access: Restricted to incident response team
Retention: Per corporate policy (7 years)

Processing Documentation

Document all processing steps:

Decryption Performed:
Date/Time: 2026-01-19 08:30:00 UTC
Tool: jenkins-credential-decryptor v1.0.0
Command: python3 decrypt.py --key master.key --secret hudson.util.Secret --xml credentials.xml --export-json decrypted.json --reveal-secrets
Output: 23 credentials successfully decrypted
Export: decrypted.json (SHA256: a1b2c3d4e5f6...)
Operator: J. Smith
Witness: K. Johnson

Export Documentation

All exports should include metadata headers:

JSON Export Format with Metadata:

{
  "metadata": {
    "case_id": "SEC-2026-001-JENKINS",
    "timestamp": "2026-01-19T08:30:00Z",
    "operator": "J. Smith",
    "tool_version": "1.0.0",
    "source_files": {
      "master_key": "4a3f2b1c8d9e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a",
      "hudson_secret": "8f7e6d5c4b3a2918f7e6d5c4b3a2918f7e6d5c4b3a2918f7e6d5c4b3a2918f7e",
      "credentials_xml": "2d4e6f8a0c2e4f6a8b0d2e4f6a8c0e2f4a6b8d0e2f4a6c8e0d2f4a6b8c0e2f4"
    }
  },
  "credentials": [
    {
      "id": 1,
      "file": "/var/jenkins_home/credentials.xml",
      "encrypted": "AQAAABAAAAAw...",
      "decrypted": "AKIAIOSFODNN7EXAMPLE",
      "credential_type": "aws_access_key"
    }
  ]
}

Docker Forensic Mode

Docker provides enhanced forensic isolation:

Read-Only Volume Mounts:

# docker-compose.yml
services:
  decryptor:
    image: jenkins-credential-decryptor
    volumes:
      - ./evidence:/data:ro          # Read-only evidence files
      - ./exports:/output:rw         # Write-only exports
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    read_only: true                  # Read-only root filesystem

Run Forensic Container:

# Start with forensic configuration
docker-compose -f docker-compose.forensic.yml run --rm decryptor \
  --path /data \
  --export-json /output/case-SEC-2026-001.json \
  --reveal-secrets

# Verify export integrity
sha256sum exports/case-SEC-2026-001.json

Benefits:

Complete filesystem isolation from host
No host file modification risk
Reproducible processing environment
Network isolation (no external connections)
Non-root execution (user: forensic)
Audit trail via Docker logs

Export Formats for Documentation

JSON Format

Structured format for programmatic processing and long-term archival:

Use Cases:

Integration with SIEM and forensic platforms
Automated credential testing and validation
Long-term case archival
Cross-reference with other evidence sources

Advantages:

Machine-readable and parseable
Preserves full structure and metadata
Standard format with wide tool support

# Export with full context
python3 decrypt.py \
  --path /var/jenkins_home \
  --export-json case-evidence.json \
  --reveal-secrets

# Parse specific credential types
jq '.[] | select(.decrypted | startswith("AKIA"))' case-evidence.json > aws_keys.json
jq '.[] | select(.decrypted | startswith("ghp_"))' case-evidence.json > github_tokens.json

CSV Format

Tabular format for reporting and spreadsheet analysis:

Use Cases:

Executive summaries and reports
Credential inventory tracking
Quick visual review and triage
Import into spreadsheet tools

Advantages:

Human-readable in text editors
Universal spreadsheet compatibility
Easy filtering and sorting

# Export to CSV
python3 decrypt.py \
  --path /var/jenkins_home \
  --export-csv case-evidence.csv \
  --reveal-secrets

# Open in Excel/LibreOffice for analysis

Markdown Reports

Human-readable format for incident reports:

Example Script (examples/generate_report.sh):

#!/bin/bash
# Generate forensic markdown report

CASE_ID="SEC-2026-001"
OUTPUT="forensic-report-${CASE_ID}.md"

cat > "$OUTPUT" << EOF
# Forensic Analysis Report

**Case ID**: ${CASE_ID}
**Date**: $(date -u +"%Y-%m-%d %H:%M:%S UTC")
**Analyst**: $(whoami)

## Executive Summary

Jenkins credential decryption completed for compromised server jenkins-prod-01.

## Evidence Files

| File | SHA256 Hash | Size |
|------|-------------|------|
| master.key | $(sha256sum master.key | cut -d' ' -f1) | $(stat -f%z master.key 2>/dev/null || stat -c%s master.key) bytes |
| hudson.util.Secret | $(sha256sum hudson.util.Secret | cut -d' ' -f1) | $(stat -f%z hudson.util.Secret 2>/dev/null || stat -c%s hudson.util.Secret) bytes |
| credentials.xml | $(sha256sum credentials.xml | cut -d' ' -f1) | $(stat -f%z credentials.xml 2>/dev/null || stat -c%s credentials.xml) bytes |

## Decrypted Credentials

Total credentials recovered: $(python3 decrypt.py --path . --dry-run 2>&1 | grep -c "Found secret")

### High-Value Findings

EOF

# Parse JSON export for high-value credentials
python3 decrypt.py --path . --export-json temp.json --reveal-secrets > /dev/null 2>&1
jq -r '.[] | select(.decrypted | startswith("AKIA")) | "- AWS Access Key: \(.decrypted | .[0:20])..."' temp.json >> "$OUTPUT"
jq -r '.[] | select(.decrypted | startswith("ghp_")) | "- GitHub Token: \(.decrypted | .[0:15])..."' temp.json >> "$OUTPUT"
rm temp.json

echo "Report generated: $OUTPUT"

Security Controls During Forensic Operations

Redaction by Default

Prevent accidental credential exposure in logs or screenshots:

# Safe mode - credentials redacted in terminal output
python3 decrypt.py --path /var/jenkins_home

# Output:
# AKIA***REDACTED***MPLE
# ghp_***REDACTED***stuv

Only use --reveal-secrets when:

Working in secure environment
Screen recording is disabled
Terminal history is disabled
Output is redirected to secure file

Dry-Run Validation

Test processing without decryption:

# Validate files and encryption without revealing secrets
python3 decrypt.py --path /var/jenkins_home --dry-run

# Output:
# [DRY RUN] Found 23 encrypted secrets
# [DRY RUN] All files validated successfully

Use cases:

Verify file integrity before processing
Test tool configuration
Demonstrate methodology without exposing evidence

Network Isolation

Ensure decryption occurs offline:

# Docker with no network access
docker-compose run --rm --network none decryptor \
  --path /data \
  --export-json /output/decrypted.json

# Verify no network connections
docker inspect <container> | jq '.[0].NetworkSettings'

Minimal Privilege Execution

Run with least privilege necessary:

# Non-root execution
docker-compose run --rm --user 1000:1000 decryptor --path /data

# Verify non-root
docker-compose run --rm decryptor whoami
# Output: forensic (not root)

Incident Response Workflow

Phase 1: Evidence Collection

# Create forensic directory structure
mkdir -p forensic-case-001/{evidence,exports,logs,reports}
cd forensic-case-001

# Extract files from compromised system
scp user@jenkins-server:/var/jenkins_home/secrets/master.key evidence/
scp user@jenkins-server:/var/jenkins_home/secrets/hudson.util.Secret evidence/
scp user@jenkins-server:/var/jenkins_home/credentials.xml evidence/

# Generate hashes
cd evidence
sha256sum * > ../logs/evidence_hashes.txt
cd ..

Phase 2: Validation

# Verify file integrity
sha256sum -c logs/evidence_hashes.txt

# Dry-run to validate files
python3 decrypt.py --path evidence --dry-run > logs/validation.log 2>&1

Phase 3: Decryption

# Decrypt with full documentation
python3 decrypt.py \
  --path evidence \
  --export-json exports/credentials.json \
  --export-csv exports/credentials.csv \
  --reveal-secrets \
  | tee logs/decryption.log

# Generate checksums of exports
sha256sum exports/* > logs/export_hashes.txt

Phase 4: Analysis

# Parse credential types
jq -r '.[] | .decrypted' exports/credentials.json | \
  grep -E '^AKIA' > reports/aws_keys.txt

jq -r '.[] | .decrypted' exports/credentials.json | \
  grep -E '^ghp_' > reports/github_tokens.txt

# Count credential types
echo "AWS Keys: $(wc -l < reports/aws_keys.txt)"
echo "GitHub Tokens: $(wc -l < reports/github_tokens.txt)"

Phase 5: Reporting

# Generate executive summary
./examples/generate_report.sh > reports/executive-summary.md

# Archive entire case
tar czf forensic-case-001.tar.gz forensic-case-001/
sha256sum forensic-case-001.tar.gz > forensic-case-001.tar.gz.sha256

Best Practices

Do

Generate and verify cryptographic hashes of all evidence files
Maintain detailed chain of custody documentation
Use Docker forensic mode for maximum isolation
Export to both JSON (archival) and CSV (reporting)
Document all processing steps with timestamps
Preserve original file metadata (timestamps, permissions)
Use read-only mounts when possible
Disable terminal history during credential revelation
Store exports in secure, access-controlled locations

Do Not

Modify original evidence files
Process evidence on production systems
Run with unnecessary elevated privileges
Enable network access during decryption
Store plaintext exports on shared network drives
Use --reveal-secrets during demonstrations or training
Copy evidence via insecure channels (unencrypted email, chat)
Process evidence without hash verification

Legal Considerations

Authorization Required: Ensure proper authorization before processing Jenkins credentials:

Incident response authorization from management
Penetration testing scope documentation
CTF competition rules compliance
Security research ethics board approval

Data Protection: Consider data protection regulations:

GDPR (EU): Personal data handling requirements
CCPA (California): Consumer data protection
HIPAA (Healthcare): Protected health information
PCI DSS (Payment cards): Cardholder data security

Evidence Admissibility: For legal proceedings:

Maintain unbroken chain of custody
Document all access to evidence
Preserve cryptographic integrity verification
Follow organizational forensic procedures
Engage legal counsel as appropriate

References

Support

For forensic deployment support, operational security questions, or technical issues:

GitHub Issues: Jenkins-Credential-Decryptor Issues
Documentation: See README.md, DOCKER_USAGE.md
Test Documentation: tests/README.md, tests/JENKINS_LAB_TESTING.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Forensic Usage Guidelines

Overview

Evidence Preservation

Read-Only Operations

File Integrity Verification

Timestamp Preservation

Chain of Custody

Evidence Documentation

Processing Documentation

Export Documentation

Docker Forensic Mode

Export Formats for Documentation

JSON Format

CSV Format

Markdown Reports

Security Controls During Forensic Operations

Redaction by Default

Dry-Run Validation

Network Isolation

Minimal Privilege Execution

Incident Response Workflow

Phase 1: Evidence Collection

Phase 2: Validation

Phase 3: Decryption

Phase 4: Analysis

Phase 5: Reporting

Best Practices

Do

Do Not

Legal Considerations

References

Support

FilesExpand file tree

FORENSICS.md

Latest commit

History

FORENSICS.md

File metadata and controls

Forensic Usage Guidelines

Overview

Evidence Preservation

Read-Only Operations

File Integrity Verification

Timestamp Preservation

Chain of Custody

Evidence Documentation

Processing Documentation

Export Documentation

Docker Forensic Mode

Export Formats for Documentation

JSON Format

CSV Format

Markdown Reports

Security Controls During Forensic Operations

Redaction by Default

Dry-Run Validation

Network Isolation

Minimal Privilege Execution

Incident Response Workflow

Phase 1: Evidence Collection

Phase 2: Validation

Phase 3: Decryption

Phase 4: Analysis

Phase 5: Reporting

Best Practices

Do

Do Not

Legal Considerations

References

Support