Admin Token Setup Guide for codex¶
Last Updated: 2026-07-11 Version: v0.2.0
Generated: 2026-06-22 Repository: Aries-Serpent/codex Security Level: (5/5) Roles: [Org Admin], [Security Officer]
Table of Contents¶
Overview¶
This guide walks administrators through setting up secure GitHub token storage for the _codex_ repository. The system supports multiple security levels:
| Method | Security | Complexity | Recommended |
|---|---|---|---|
| AES-256-GCM | Medium | Production | |
| Base64 | Low | Development/Testing | |
| Hex | Low | Alternative encoding |
Prerequisites¶
Required Access¶
- GitHub Organization Owner or Admin role
- Repository Admin access to
Aries-Serpent/_codex_ - GitHub CLI (
gh) installed and authenticated
Required Tools¶
# Check installed tools
gh --version # GitHub CLI
python3 --version # Python 3.8+
pip3 --version # Python package manager
# Install cryptography library (for AES encryption)
pip3 install cryptography
Setup Process¶
Step 1: Generate GitHub Personal Access Token¶
- Navigate to: https://github.com/settings/tokens/new
- Configure token:
- Note:
_codex_ Copilot Agent Token - Expiration: 90 days (recommended)
- Scopes: Select:
-
repo(Full control of private repositories) -
workflow(Update GitHub Action workflows) -
admin:org(if org-level operations needed) - Click Generate token
- COPY THE TOKEN (you won't see it again)
Step 2: Run Encryption Tool¶
# Clone repository if not already done
git clone https://github.com/Aries-Serpent/_codex_.git
cd _codex_
# Install dependencies
pip3 install -r scripts/security/requirements.txt
# Run encryption tool
python3 scripts/security/token_encryption_tool.py
# When prompted, paste your GitHub token
# The tool will generate encrypted values
Example output:
_CODEX_ TOKEN ENCRYPTION TOOL v2.0 # pragma: allowlist secret
Energy: 5/5 | Security Mode Active
================================================================================
Enter GitHub token: ghp_PLACEHOLDER_EXAMPLE_TOKEN # pragma: allowlist secret
Encryption complete!
COPY THESE VALUES TO GITHUB SECRETS: # pragma: allowlist secret
RECOMMENDED - Base64 Encoding:
Secret Name: CODEX_GHP_TOKEN_BASE64 # pragma: allowlist secret
Secret Value: Z2hwX3h4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4 # pragma: allowlist secret
MOST SECURE - AES-256-GCM Encryption:
Secret Name: CODEX_GHP_TOKEN_AES_KEY # pragma: allowlist secret
Secret Value: dGVzdGtleXZhbHVlZm9yZGVtb25zdHJhdGlvbnB1cnBvc2VzMTIz # pragma: allowlist secret
...
Step 3: Add Secrets to GitHub¶
Option A: Automated (Recommended)¶
The encryption tool generates a setup script:
Option B: Manual via GitHub CLI¶
# Set repository secrets using gh CLI
gh secret set CODEX_GHP_TOKEN_BASE64 --body "YOUR_BASE64_VALUE" --repo Aries-Serpent/_codex_
gh secret set CODEX_GHP_TOKEN_AES_KEY --body "YOUR_AES_KEY" --repo Aries-Serpent/_codex_
# Add other secrets as needed...
Option C: Manual via Web UI¶
- Navigate to: https://github.com/Aries-Serpent/codex/settings/secrets/actions
- Click New repository secret
- For each secret:
- Name: (from encryption tool output)
- Value: (from encryption tool output)
- Click Add secret
Step 4: Revoke Original Token¶
CRITICAL: After verifying the setup works, revoke the original token:
- Navigate to: https://github.com/settings/tokens
- Find the token you just created
- Click Delete or Revoke
- Generate a new token if needed for other purposes
Verification¶
Test Token Retrieval¶
# Method 1: Direct test
python3 -c "
from scripts.security.token_encryption_tool import copilot_get_github_token_safe
token = copilot_get_github_token_safe()
print(' Token retrieved successfully' if token else ' Token retrieval failed')
"
# Method 2: Full integration test
python3 scripts/security/token_encryption_tool.py
Test in Workflow¶
Trigger a test workflow run:
gh workflow run copilot-automation.yml --repo Aries-Serpent/_codex_
# Check workflow logs
gh run list --workflow=copilot-automation.yml --limit 1
Token Rotation¶
Recommendation: Rotate tokens every 90 iterations.
Rotation Process¶
- Generate new GitHub token (see Step 1)
- Run encryption tool with new token
- Update GitHub secrets with new values
- Test token retrieval
- Revoke old token
- Document rotation in security log
Automated Rotation (Future Enhancement)¶
Create calendar reminder or use GitHub Actions scheduled workflow to alert when rotation is due.
Troubleshooting¶
Issue: "No GitHub token found in environment secrets"¶
Symptoms: Copilot Agent cannot retrieve token
Solutions:
1. Verify secrets are set in repository settings
2. Check secret names match exactly (case-sensitive)
3. Confirm workflow has correct env: mapping
4. Test locally with environment variables
# Test locally
export CODEX_GHP_TOKEN_BASE64="your_base64_value"
python3 scripts/security/token_encryption_tool.py
Issue: "Token verification failed: invalid format or hash mismatch"¶
Symptoms: Token retrieved but fails validation
Solutions: 1. Regenerate encryption with same token 2. Ensure SHA-256 secret is correct 3. Check for whitespace/newlines in secret values 4. Verify token hasn't been revoked
Issue: "AES decryption unavailable: cryptography library not installed"¶
Symptoms: AES encrypted token cannot be decrypted
Solutions: 1. Install cryptography library:
2. Add to workflow: 3. Use Base64 encoding as fallbackSecurity Best Practices¶
Token Permissions¶
- Use least privilege principle (minimum required scopes)
- Set expiration date (90 days recommended)
- Enable SSO/SAML if available
- Use fine-grained tokens when possible
Secret Management¶
- Never commit tokens to repository
- Use repository secrets (not hardcoded in workflows)
- Rotate tokens regularly
- Revoke compromised tokens immediately
- Enable audit logging for secret access
Access Control¶
- Limit repository admin access
- Review secret access logs regularly
- Use environment protection rules
- Enable branch protection with required reviews
Support & Resources¶
Documentation:
- Encryption Tool: scripts/security/token_encryption_tool.py
- Token Scope Verification: scripts/security/verify_token_scope.py
- Copilot Usage Guide: docs/admin/security/COPILOT_TOKEN_USAGE.md
GitHub Resources: - Creating a Personal Access Token - Encrypted Secrets
Contact:
- Security Issues: Create issue with security label
- General Questions: Discussion board
Last Updated: 2026-06-22T00:00:00Z Version: 2.0.0 Maintainer: Security Team
Mission Overview¶
Objective: Enable secure token management for AI agents through AES-256-GCM encryption with zero plaintext exposure.
Energy Level: (5/5 - Security Critical)
Status: Active
Verification Checklist¶
Configuration Validation¶
- GitHub Personal Access Token generated with correct scopes
- Token encrypted using encryption tool successfully
- All required secrets (Base64 or AES) added to GitHub
- Encryption key safely stored in password manager
- Local test confirms token retrieval works
Security Verification¶
- Original plaintext token revoked from GitHub settings
- SHA-256 hash verification passes
- Setup script and terminal history cleaned
- Rotation reminder scheduled for 90 iterations
- No tokens visible in repository code or logs
Success Metrics¶
| Metric | Current | Target | Status |
|---|---|---|---|
| Token Encryption Method | AES-256-GCM | AES-256-GCM | |
| Token Rotation Frequency | 90 iterations | 90 iterations | |
| Plaintext Exposure | 0 instances | 0 instances | |
| Secret Validation | SHA-256 | SHA-256 | |
| Setup Completion Time | 30-45 min | <60 min |
Physics Alignment¶
| Principle | Application | Implementation |
|---|---|---|
| Path | Clear progression from token generation to secure storage | 5-phase setup: Generate Encrypt Configure Verify Cleanup |
| Fields | Token transformation from plaintext to encrypted state | Multiple encoding layers: Plaintext AES-256-GCM Base64 GitHub Secret |
| Patterns | Recognition of security best practices | SHA-256 verification, expiration dates, automated rotation reminders |
| Redundancy | Fallback encryption methods if primary fails | Fallback chain: AES-256-GCM Base64 Hex Manual entry |
| Balance | Security strength vs operational usability | Military-grade encryption with automated setup scripts |
Energy Distribution¶
| Phase | Energy | Rationale |
|---|---|---|
| Token Generation | Foundation - incorrect scopes render system non-functional | |
| Encryption Process | Critical - protects token from compromise | |
| Secret Configuration | High priority - enables retrieval by automation | |
| Verification Testing | Essential - confirms end-to-end functionality | |
| Security Cleanup | Critical - eliminates plaintext exposure vectors |
Total Energy Investment: 23/25 units
Redundancy Patterns¶
Rollback Strategy: If encrypted token fails, immediately generate new token and re-run encryption process with verified parameters.
Parallel Paths: - If AES-256-GCM decryption fails Use Base64 encoding fallback - If automated setup script fails Use manual GitHub CLI commands - If GitHub CLI unavailable Use web UI manual configuration - If token verification fails Regenerate encryption with same token and update secrets
Recovery Procedures:
1. Token Retrieval Failure: Export CODEX_GHP_TOKEN_BASE64 locally, test decoder module, verify secret names match exactly
2. Encryption Tool Error: Install cryptography library, ensure Python 3.8+, re-run tool with clean terminal
3. Verification Hash Mismatch: Regenerate all secrets simultaneously, ensure no whitespace/newlines in values
4. Compromised Token Detection: Revoke immediately, generate new token, rotate all secrets within 24 hours