Skip to content

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

  1. Overview
  2. Prerequisites
  3. Setup Process
  4. Verification
  5. Token Rotation
  6. Troubleshooting

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

  1. Navigate to: https://github.com/settings/tokens/new
  2. Configure token:
  3. Note: _codex_ Copilot Agent Token
  4. Expiration: 90 days (recommended)
  5. Scopes: Select:
  6. repo (Full control of private repositories)
  7. workflow (Update GitHub Action workflows)
  8. admin:org (if org-level operations needed)
  9. Click Generate token
  10. 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

The encryption tool generates a setup script:

# Run the generated setup script
bash ~/codex_token_setup.sh

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

  1. Navigate to: https://github.com/Aries-Serpent/codex/settings/secrets/actions
  2. Click New repository secret
  3. For each secret:
  4. Name: (from encryption tool output)
  5. Value: (from encryption tool output)
  6. Click Add secret

Step 4: Revoke Original Token

CRITICAL: After verifying the setup works, revoke the original token:

  1. Navigate to: https://github.com/settings/tokens
  2. Find the token you just created
  3. Click Delete or Revoke
  4. 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

  1. Generate new GitHub token (see Step 1)
  2. Run encryption tool with new token
  3. Update GitHub secrets with new values
  4. Test token retrieval
  5. Revoke old token
  6. 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:

pip3 install cryptography
2. Add to workflow:
- name: Install cryptography
run: pip install cryptography
3. Use Base64 encoding as fallback


Security 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