Token Auto-Refresher

A powerful Burp Suite extension that automatically captures and injects fresh bearer tokens into your security testing workflow, eliminating authentication failures during automated scans.

🎯 Overview

The Token Auto-Refresher extension solves a common problem in web application security testing: expired authentication tokens during automated scans. Instead of manually updating tokens or dealing with 401/403 responses, this extension automatically:

• Captures fresh bearer tokens from your proxy traffic
• Stores tokens per host for organized management
• Injects current tokens into Scanner, Intruder, Repeater, and other tool requests
• Refreshes tokens using time-based requests when needed
• Persists all settings per Burp project

✨ Key Features

🔄 Multi-Source Token Capture

• Proxy History: Automatically extracts tokens from manual browsing
• Time-Based Refresh: Configurable automated token renewal requests
• Flexible Header Configuration: Unified template system for extraction and injection
• Custom Patterns: Flexible regex-based token extraction
• Multiple Headers: Supports Authorization, X-Auth-Token, X-Access-Token, X-Api-Key and any custom headers

⚙️ Multi-Tool Integration

• Scanner: Keep automated scans authenticated
• Intruder: Maintain authentication during attacks
• Repeater: Always use fresh tokens in manual testing
• Sequencer: Authenticated entropy analysis
• Extensions: Token injection for other Burp extensions

📊 Smart Token Management

• Host-Based Token Table: Visual display of all captured tokens organized by host with copy-to-clipboard functionality
• Automatic Updates: Real-time token refresh and lifecycle management
• Project Persistence: Token settings saved per Burp project automatically

🚀 Installation

Option 1: Download Pre-built JAR

1. Go to Releases and download the latest token-auto-refresher.jar
2. Open Burp Suite Professional or Community
3. Go to Extensions → Installed → Add
4. Select Extension type: Java
5. Choose the downloaded .jar file

Option 2: Build from Source

1. Clone this repository
2. Run ./gradlew build to compile the extension
3. The JAR file will be created at build/libs/bearer-token-auto-refresher.jar
4. Load the JAR file into Burp using the steps above

📖 Usage Guide

Basic Setup

1. Enable the Extension

   • Check "Enable automatic token refresh" in the main panel
   • The extension starts monitoring proxy traffic immediately

2. Configure Tool Integration

   • Select which tools should receive token injection:
     • ✅ Scanner (recommended - enabled by default)
     • ⬜ Intruder
     • ⬜ Repeater
     • ⬜ Sequencer
     • ⬜ Other Extensions

3. Browse the Target Application

   • Use Burp's browser to authenticate normally
   • The extension automatically captures bearer tokens from responses
   • Watch the "Current Tokens" table populate with captured tokens

Advanced Configuration

Time-Based Token Refresh

For applications requiring periodic token renewal:

1. Enable Time-Based Requests

   • Check "Time-based Requests" in Token Refresh Sources
   • Note: When both Proxy and Time-based are enabled, Time-based tokens take priority for the configured host

2. Configure the Refresh Request

   • Host: Target authentication endpoint (e.g., api.example.com)
   • Interval: Refresh frequency in seconds (e.g., 300 for 5 minutes)
   • Method: HTTP method (GET/POST/PUT)
   • Request Configuration: Full HTTP request template:

     POST /api/auth/refresh HTTP/1.1
     Host: api.example.com
     Content-Type: application/json
     Authorization: Bearer {current_token}
     
     {"refresh_token": "your_refresh_token"}
     

3. Configure Token Extraction

   • Extract from: Choose "Header" or "Response Body"
   • Header extraction: Specify header name (e.g., "Authorization")
   • Body extraction: Define start/end patterns:
     • Start pattern: "refresh_token": "
     • End pattern: "

4. Start Automatic Refresh

   • Click "Start" to begin automated token renewal
   • Monitor the status indicator (🟢 RUNNING / 🔴 STOPPED)

Token Configuration

The extension provides unified configuration that controls both token extraction and injection:

Token Extraction Pattern (Regex)

• Default: Bearer\s+([A-Za-z0-9\-\._~\+\/]+=*)
• Captures the token value from header contents
• Customizable for non-standard token formats

Header Template (Extract & Inject)

• Format: HeaderName: Prefix [TOKEN] Suffix
• Controls which header to check and how tokens are formatted
• Common presets:
  • Authorization: Bearer [TOKEN] - Standard RFC 6750 bearer tokens
  • Authorization: [TOKEN] - Raw tokens without prefix
  • X-Api-Key: [TOKEN] - Custom API key headers
  • Access-Token: [TOKEN] - Alternative authentication headers

Note: You can define your own custom header template for any authentication scheme your application uses.

This unified approach ensures tokens are extracted from and injected into the same header, providing consistency across your testing workflow.

🔧 Configuration Examples

Example 1: Extract JWT Token from JSON Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Configuration:

• Extract from: Response Body
• Start pattern: "access_token":"
• End pattern: "

Example 2: Extract Token from Header

HTTP/1.1 200 OK
X-Auth-Token: abc123def456ghi789
Content-Type: application/json

Configuration:

• Extract from: Header
• Header name: X-Auth-Token

Example 3: Custom API Key Header

GET /api/data HTTP/1.1
Host: api.example.com
X-Api-Key: Bearer sk_live_abc123def456

Configuration:

• Header Template: X-Api-Key: Bearer [TOKEN]
• Token Extraction Pattern: Bearer\s+([A-Za-z0-9\-\._~\+\/]+=*)

📊 Project Persistence

The extension automatically saves all settings per Burp project:

• ✅ Project-Specific: Each project maintains its own configuration
• ✅ Temporary Projects: Use default settings (no persistence)

Saved Settings Include:

• Extension enabled/disabled state
• Tool injection preferences
• Token source selections
• Time-based configuration (host, interval, request template)
• Token extraction settings (patterns, headers)
• Custom token regex patterns

📊 Log Analysis

• Injection Logs: Shows when tokens are injected
• Capture Logs: Indicates when new tokens are discovered
• Error Logs: Displays configuration or network issues
• Show Response Button: Displays the latest time-based refresh response in logs for debugging
• Export Logs: Save complete activity log for analysis

Contributors

Contributor	Module
Vasilis Flengas	Idea, Development

Community

Join the Hackcraft community discord server here. On the server you can receive support and discuss issues related to Token Auto Refresher.