SOCproof

Your automated sidekick for SOC 2 compliance and PR documentation 🤖

✨ Features

📊 PR Reporter

Generate comprehensive CSV reports of your merged PRs including:

• PR metadata (ID, title, state)
• Target branches
• Timeline (created/merged dates)
• Approver information
• Direct links to PRs

📸 PR Evidence

Automated screenshot collection for compliance:

• PR conversations
• CI/CD checks
• Perfect for SOC 2 audit evidence

🚀 Quick Start

# Install
git clone https://github.com/davidfeldi/socproof.git
cd socproof
pip install -r requirements.txt

# Set up credentials
export GITHUB_TOKEN="your_github_token"
export GITHUB_OWNER="your_org_name"

# Generate PR Report
python -m src.pr_reporter your-repo-name --since 2024-01-01

# Collect PR Evidence
python -m src.pr_evidence

📖 Detailed Usage

PR Reporter

python -m src.pr_reporter your-repo-name \
    --since 2024-01-01 \
    --until 2024-03-01 \
    --output-dir ./reports

Output Example

id,number,title,state,target_branch,created_at,merged_at,approvers,url
12345,42,"Add awesome feature","closed","main","2024-01-01T10:00:00Z","2024-01-02T15:30:00Z","alice, bob","https://github.com/..."

PR Evidence

# Using command line arguments
python -m src.pr_evidence --titles "PR title 1" "PR title 2" "PR title 3"

# Using a file with PR titles
echo "PR title 1
PR title 2
PR title 3" > pr_titles.txt

python -m src.pr_evidence --titles-file pr_titles.txt

You can also combine both approaches:

python -m src.pr_evidence \
    --titles "PR title 1" \
    --titles-file pr_titles.txt \
    --output-dir ./evidence \
    --headless

The script will:

1. Open a Chrome browser window
2. Navigate to GitHub login page
3. Pause with message: "Please login manually in the browser and press Enter to continue..."
4. After you log in and press Enter, it will:
   • Search for each PR by title
   • Capture conversation screenshots
   • Capture checks screenshots
   • Save all evidence to pr_evidence/ directory

💡 Note: Manual login is required for security reasons. Your GitHub credentials are never stored.

Generated Evidence

pr_evidence/
├── pr_42_20240301_123456_conversation.png
└── pr_42_20240301_123456_checks.png

💡 Tip: For best results, use exact PR titles as they appear in GitHub (or use the PR Reporter to get the exact title).

🔧 Requirements

• Python 3.8+
• GitHub Personal Access Token with repo scope
• Chrome/Chromium browser (for PR Evidence)

👩‍💻 Development

# Setup dev environment
pip install -r requirements.txt

# Run tests
pytest tests/

# Run with debug logging
DEBUG=1 python -m src.pr_reporter your-repo-name

🤝 Contributing

Contributions are welcome! Here's how:

1. 🍴 Fork the repository
2. 🌿 Create your feature branch (git checkout -b feature/amazing)
3. 💾 Commit changes (git commit -am 'Add amazing feature')
4. 🚀 Push to branch (git push origin feature/amazing)
5. 📬 Open a Pull Request

🔒 Security

• Never commit tokens to the repository
• Use environment variables for sensitive data
• Review GitHub token permissions regularly

📄 License

MIT License - see LICENSE file for details

---

Made with ❤️ by the SOCproof Team