---

Title: Permissions & Security. Description: Understanding GitHub App permissions and security.

PERMISSIONS & SECURITY

Learn what permissions the CAPYSQUASH GitHub App requires and how your data is protected.

REQUIRED PERMISSIONS

The GitHub App requires minimal permissions to function:

Repository Permissions

WHAT WE ACCESS

📝

• PULL REQUESTS - READ & WRITE

• Why we need it:

• ► Read PR details and changed files

• ► Post analysis results as comments

• ► Read manual trigger commands

• What we DON'T do:

• ► Never merge or close PRs

• ► Never modify PR descriptions

• ► Never request reviews

• 📁

• CONTENTS - READ ONLY

• Why we need it:

• ► Read migration files from configured paths

• ► Detect changed files in PRs

• What we DON'T do:

• ► Never write or modify files

• ► Never create commits

• ► Never read outside migration paths

• ☑

• CHECKS - READ & WRITE

• Why we need it:

• ► Create status checks on PRs

• ► Update check status (pass/fail)

• ► Add check details and links

• What we DON'T do:

• ► Never modify other checks

• ► Never bypass required checks

• ℹ️

• METADATA - READ ONLY

• Why we need it:

• ► Repository name and description

• ► Repository visibility (public/private)

• ► Default branch information

• Standard GitHub permission - cannot be disabled

Organization Permissions

ORGANIZATION ACCESS (OPTIONAL)

👥

• MEMBERS - READ ONLY

• Why it's optional:

• ► Only for organization-wide installations

• ► Helps identify team members vs external contributors

• ► Not required for functionality

Webhook Events

The app subscribes to these events:

Note: We ignore all other webhooks (issues, commits, deployments, etc.)

WHAT WE ACCESS

We DO Access

☑ Migration files only.

• Files in configured migration paths
• Only when PR changes them
• During analysis only

☑ PR metadata.

• PR number, title, author
• Changed files list
• Target branch

☑ Repository info.

• Repository name
• Owner/organization
• Visibility status

We DON'T Access

☒ Your code.

• Application code
• Configuration files
• Secrets/environment variables
• Any files outside migration paths

☒ Sensitive data.

• Database credentials
• API keys
• User data
• Business logic

☒ Other repositories.

• Only access repositories you explicitly install on

DATA HANDLING

What We Store

In CAPYSQUASH cloud:

• Analysis results (warnings, recommendations)
• Migration file metadata (name, size, timestamp)
• PR metadata (number, title, link)
• Repository name and link

We do NOT store:

• Full migration file contents (discarded after analysis)
• Your database schema (only temporary during analysis)
• Any data from your database
• Code from other parts of repository

Data Retention

Data Location

• Servers: US/EU (depending on your region selection)
• Database: Encrypted at rest
• In transit: TLS 1.3 encryption
• Backups: Encrypted, 30-day retention

SECURITY MEASURES

Infrastructure Security

🔒 ENCRYPTION

► TLS 1.3 in transit ► AES-256 at rest ► Encrypted backups

🛡️ ISOLATION

► Separate analysis environments ► Network isolation ► No cross-tenant access

🔐 ACCESS CONTROL

► Role-based permissions ► Audit logging ► 2FA for team members

• 📋 COMPLIANCE

• ► SOC 2 Type II (in progress)

• ► GDPR compliant

• ► Regular security audits

Analysis Environment

Each analysis runs in isolated environment:

• Secure Container
• ├── Temporary file system (ephemeral)
• ├── No network access (except CAPYSQUASH API)
• ├── Read-only migration files
• ├── No persistent storage
• └── Destroyed after analysis

Security features:

• No internet access during analysis
• Cannot make external API calls
• Cannot write to your repository
• Cannot access other organizations' data

GitHub App Security

OAuth flow:

• Standard GitHub OAuth
• Scoped access tokens
• Token rotation
• Revocable anytime

Webhook verification:

• HMAC signature validation
• Replay attack prevention
• IP allowlist (optional)

PERMISSION UPDATES

When CAPYSQUASH needs new permissions:

UPDATE PROCESS

1

• NOTIFICATION

• We email you and show banner in dashboard explaining why

• 2

• YOUR CHOICE

• You approve or reject - app stops working until approved

• 3

• GITHUB APPROVAL

• Redirect to GitHub to accept new permissions

• 4

• RESUME SERVICE

• App continues with new permissions

Note: We will NEVER add permissions without your explicit approval.

REVOKING ACCESS

You can revoke access anytime:

From CAPYSQUASH

• Dashboard → Organization → Settings → Integrations → GitHub → Disconnect

What happens:

• Analysis stops immediately
• Webhook subscriptions removed
• Historical data preserved (but not accessible via GitHub)
• Can reconnect later

From GitHub

• GitHub Settings → Applications → Installed GitHub Apps → CAPYSQUASH → Uninstall

What happens:

• Same as disconnecting from CAPYSQUASH
• Plus: All permissions revoked in GitHub
• OAuth tokens invalidated

ORGANIZATION POLICIES

Third-Party App Restrictions

If your GitHub organization restricts third-party apps:

1. Organization admin must approve CAPYSQUASH
2. Go to: Organization Settings → Third-party access → GitHub Apps
3. Review CAPYSQUASH and approve
4. Then install normally

IP Allowlists

If your organization uses IP allowlists:

CAPYSQUASH IP ranges:

• US Region:

• 35.123.45.0/24

• 35.123.46.0/24

• EU Region:

• 52.234.56.0/24

• 52.234.57.0/24

Add these to your GitHub organization allowlist.

Single Sign-On (SSO)

For organizations with SAML SSO:

1. Install app normally
2. Authorize SSO for CAPYSQUASH
3. Go to: GitHub Settings → Applications → CAPYSQUASH → Configure SSO
4. Authorize for your organization

Note: SSO authorization required per organization.

AUDIT LOGGING

Track all GitHub App activity:

In CAPYSQUASH Dashboard

• Organization → Settings → Audit Log

See:

• App installations/uninstallations
• Permission changes
• Analysis triggers
• Configuration changes
• Team member actions

In GitHub

• Organization Settings → Audit log

Filter by app:CAPYSQUASH to see:

• Installation events
• Repository access
• Permission grants
• Webhook deliveries

SECURITY BEST PRACTICES

For Organizations

1. Review permissions regularly

• Check what CAPYSQUASH can access
• Verify only necessary repositories

2. Enable SSO (if available)

• Additional authentication layer
• Centralized access control

3. Monitor audit logs

• Review GitHub App activity
• Watch for unexpected behavior

4. Limit repository access

• Install only on repos that need it
• Don't use "All repositories" unless necessary

For Developers

1. Use strong passwords

• On both GitHub and CAPYSQUASH accounts
• Enable 2FA

2. Review PR comments

• Don't ignore security warnings
• Understand what CAPYSQUASH reports

3. Don't commit secrets

• Keep credentials out of migrations
• Use environment variables

COMPLIANCE

GDPR

Data subject rights:

• ☑ Right to access: Export your data anytime
• ☑ Right to deletion: Delete projects/data
• ☑ Right to portability: Download analysis results
• ☑ Right to object: Stop processing by disconnecting

Legal basis: Legitimate interest (service functionality)

SOC 2 Type II

Currently in audit process. Expected completion: Q2 2024.

Covered:

• Security
• Availability
• Confidentiality
• Processing integrity

Data Processing Agreement (DPA)

Available for Enterprise plan:

• Custom data retention
• Specific security controls
• Liability terms
• Compliance requirements

Request DPA →

INCIDENT RESPONSE

If you suspect a security issue:

Report Security Vulnerabilities

DO:

• Email: security@CAPYSQUASH.dev
• Encrypted: PGP Key
• Include: Description, impact, reproduction steps

DON'T:

• Post publicly on GitHub
• Share in Discord/Slack
• Announce before patched

Response time:

• Acknowledgment: <24 hours
• Assessment: <72 hours
• Fix (if valid): Depends on severity

What We Do

1. Investigate reported issue
2. Develop fix if vulnerability confirmed
3. Deploy patch to production
4. Notify affected customers
5. Public disclosure after patch deployed

TRUST & TRANSPARENCY

Open About Security

• Public security policy
• Transparent permission requirements
• Clear data handling practices
• Responsive to concerns

Regular Updates

• Security patches applied promptly
• Dependencies kept up to date
• Infrastructure reviewed quarterly
• Third-party audits

Bug Bounty Program

Coming soon: Report security issues for rewards.

Details at: CAPYSQUASH.dev/security

FREQUENTLY ASKED QUESTIONS

SECURITY FAQ

Can CAPYSQUASH access my production database?

No. We only analyze migration files, never connect to your database.

• Do you store my migration files?

• No. We analyze them and discard immediately. Only metadata stored (filename, size, etc).

• Can you modify my code?

• No. We only have read access to contents, and only write to PR comments and checks.

• What happens if CAPYSQUASH is compromised?

• Worst case: Attacker could read migration files from configured paths. Cannot modify repos, access databases, or access other files.

• Do you share data with third parties?

• No, except: GitHub (for OAuth), Stripe (for billing), and infrastructure providers (AWS/GCP). Never sold or shared with advertisers.

• Is my data encrypted?

• Yes. TLS 1.3 in transit, AES-256 at rest. All data encrypted.

NEXT STEPS

🔌 API REFERENCE Integrate CAPYSQUASH programmatically

🔧 TROUBLESHOOTING Solve common issues

CONTACT SECURITY TEAM

• 📧 General: security@CAPYSQUASH.dev
• 🔐 Vulnerabilities: security@CAPYSQUASH.dev (PGP available)
• 📄 Legal/DPA: legal@CAPYSQUASH.dev
• 🎫 Support: support@CAPYSQUASH.dev