This document describes security practices and procedures for the Aetherscan project.

If you discover a security vulnerability in Aetherscan:

1. Open a GitHub Discussion with the "security" label
2. Provide a clear description of the vulnerability
3. Include steps to reproduce if applicable
4. Suggest a fix if you have one

For vulnerabilities that could expose sensitive data or allow unauthorized access:

1. Do NOT open a public issue
2. Contact Zach directly on Slack (preferred) or via email
3. Include:
   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact
   • Suggested remediation (if any)
4. Allow up to 48-72 hours for initial response
5. Work with maintainers on coordinated disclosure

If a security incident occurs:

1. Contain: Revoke compromised credentials immediately
2. Assess: Determine what was accessed or modified
3. Notify: Alert affected parties and maintainers
4. Remediate: Fix the vulnerability and rotate all potentially affected secrets
5. Document: Record the incident for future reference
6. Improve: Update processes to prevent recurrence

If you suspect a token has been compromised, rotate immediately:

1. Go to Slack API
2. Select the Aetherscan app
3. Navigate to "OAuth & Permissions"
4. Click "Revoke Tokens"
5. Reinstall the Aetherscan app and generate a new token with the following scopes: channels:read, chat:write, files:write, groups:read, incoming-webhook
6. Update SLACK_BOT_TOKEN in all deployment environments
7. Verify the new token works: PYTHONPATH=src python utils/print_cli_help.py train (should not show Slack errors)

Aetherscan uses the following secrets that must be protected:

1. Never commit secrets to the repository

   • Use environment variables or .env files
   • .env files are in .gitignore

2. Use separate tokens for development and production

   • Development tokens should have limited permissions
   • Production tokens should be rotated regularly

3. Store secrets securely

   • Use a secrets manager (e.g., HashiCorp Vault or Google Secrets Manager)
   • Or encrypted environment files with restricted permissions

4. Audit access regularly

   • Review who has access to production secrets
   • Remove access for inactive contributors

The project uses gitleaks as a pre-commit hook to prevent accidental secret commits.

• API keys and tokens
• GCP/AWS credentials
• Private keys (RSA, DSA, etc.)
• Generic secrets patterns
• High-entropy strings

# Install gitleaks
brew install gitleaks  # macOS
# or
apt-get install gitleaks  # Ubuntu

# Scan the repository
gitleaks detect --source . --verbose

# Scan specific commits
gitleaks detect --source . --log-opts="HEAD~10..HEAD"

If gitleaks flags a non-secret (e.g., a test fixture):

1. Add the specific file/line to .gitleaksignore:

   # .gitleaksignore
   tests/fixtures/mock_data.py:42
   

2. Use inline comments (less preferred):

   fake_token = "test_token_abc123"  # gitleaks:allow

The repository uses GitHub's Dependabot for automated dependency vulnerability detection.

# Using pip-audit
pip install pip-audit
pip-audit

# Using safety
pip install safety
safety check

When pinning or bumping a dependency, prefer a proven release over the bleeding edge. Consider only final/stable releases — never pre-releases (alpha / beta / rc / dev) or nightly builds. The default target is the higher (newer) of:

• two minor releases below the latest stable release (e.g. latest stable 1.8.x → target the latest patch of 1.6.x); or
• the latest stable release that is at least 6 months old.

This deliberately trails the newest release: brand-new versions are where regressions and freshly introduced (not-yet-disclosed) vulnerabilities surface, so letting a release "bake" for a couple of minors / six months trades a small amount of currency for stability and a wider window for advisories to come to light.

Exception — known advisories override the lag. If the version selected by the rule above is itself affected by a known security advisory, instead pin the minimum version that resolves the advisory, even if it is newer than the default target (see Responding to Vulnerabilities below).

These targets are additionally bounded by the project's intentional version ceilings (e.g. numpy<2.0, setuptools<81) and the NGC TensorFlow 2.17 ABI — never select a version that crosses a documented upper bound. See the header comments in environment.yml and requirements-container.txt for the rationale behind each ceiling, and keep the coupled manifests (environment.yml, requirements-container.txt, aetherscan.def) in lockstep when bumping a shared dependency.

1. Critical/High severity: Update immediately and release a patch
2. Medium severity: Update in next minor release
3. Low severity: Update in next major release or when convenient

• All major outputs (e.g. model weights, source code, search results, training/inference data, etc.) are publicly disclosed and made available via the appropriate channels (e.g. HuggingFace, GitHub, publications, Breakthrough Listen's Open Data Archive, etc.)
• Intermediate data products (e.g. db records or plots) are generally stored on secure, access-controlled HPC servers and not made available to the public. Contact @zachtheyek on Slack to discuss further

• Security issues: @zachtheyek on Slack
• General questions: Open a GitHub Discussion or Slack thread