A Comprehensive Burp Suite Extension for Authorization Testing & Session Security Analysis

Version 1.1.15 · Author: Denis Ivan

• Docs Index: docs/README.md
• Quick Start: docs/quick-start.md

1. Introduction
   • What is SessionGuard Analyzer?
   • Key Capabilities
   • Why Choose SessionGuard?
2. Architecture & Design
   • System Architecture
   • Request Processing Flow
   • Session Validation & Renewal Flow
   • Components
3. Installation & Setup
   • Prerequisites
   • Build from Source
   • Install in Burp Suite
   • First-Time Configuration
4. Core Concepts
   • Sessions
   • Tokens & Parameters
   • Extraction Methods
   • Replacement Mechanisms
   • Bypass Detection
5. User Interface Guide
   • Main Panel Overview
   • Session Management Panel
   • Session Monitoring Panel
   • Results Table & Analysis
6. Parameter Extraction & Replacement
   • Auto Extract
   • From-To String Extraction
   • Static Values
   • Prompt for Input
   • Replacement Locations
   • Parameter Removal
7. Session Monitoring & Renewal
   • Session Validation Configuration
   • Renewal Macros
   • Macro Steps & Placeholders
   • Validation States & Lifecycle
   • Failure Handling
8. Processing & Filtering
   • Scope Management
9. Testing Scenarios & Use Cases
10. Advanced Features
11. Troubleshooting & FAQ
12. Developer Guide
13. Appendix
14. License

SessionGuard Analyzer is a Burp Suite extension that discovers authorization vulnerabilities and session security issues by replicating requests across user sessions, monitoring session health, and analyzing response differences. It automates multi-role testing and reduces manual effort while keeping sessions valid via self-healing renewal macros.

• Intelligent multi-session testing with cloning and scoping
• Automatic extraction of tokens from Set-Cookie, HTML forms, JSON
• Generic From-To extraction for custom formats (e.g., JS vars)
• Flexible request mutation (headers, cookies, params, body, path)
• Bypass detection with SAME/SIMILAR/DIFFERENT heuristics
• Scheduled session validation and self-healing via renewal macros
• Quick filters, rich diffing, and HTML/XML export for reporting

• Zero preflight: operates on your natural browsing traffic
• Dynamic token discovery and replacement with minimal setup
• Self-healing sessions keep long test runs reliable
• Placeholder system for macro steps: [[tokenName]]
• Real-time, multi-role analysis with status chips and filters

flowchart LR
   subgraph BurpSuite[Burp Suite]
      subgraph Extension[SessionGuard Extension]
         BE[BurpExtender]
         HL[HttpListener]
         CC[CurrentConfig]
         RF[Request Filter Chain]
         RC[RequestController]
         RMH[RequestModifHelper]
         EH[ExtractionHelper]
         SVM[SessionValidationManager]
         SME[SessionMacroExecutor]
         UI[UI Layer: Panels & Dialogs]
         BE --> HL --> CC
         HL --> RF --> CC --> RC
         RC --> RMH
         RC --> EH
         SVM --> SME
         CC --> SVM
         CC --> UI
      end
   end

sequenceDiagram
   participant Browser
   participant HttpListener
   participant FilterChain
   participant CurrentConfig
   participant RequestController
   participant BurpAPI as Burp API

   Browser->>HttpListener: HTTP Request observed
   HttpListener->>FilterChain: Apply filters (scope, filetype, method, ...)
   alt Filtered Out
      FilterChain-->>HttpListener: Drop
   else Eligible
      FilterChain-->>CurrentConfig: Enqueue work
      loop For each Session
         CurrentConfig->>RequestController: analyze(original)
         RequestController->>RequestController: Extract tokens if present
         RequestController->>RequestController: Mutate request (headers/params/body/path)
         RequestController->>BurpAPI: makeHttpRequest(mutated)
         BurpAPI-->>RequestController: Response
         RequestController->>RequestController: Compute bypass status
         RequestController-->>CurrentConfig: Analyzer result
         CurrentConfig-->>UI: Update table & diff view
      end
   end

stateDiagram-v2
   [*] --> UNKNOWN
   UNKNOWN --> VALID: First successful validation
   UNKNOWN --> EXPIRED: First failure
   VALID --> VALID: Periodic validation OK
   VALID --> EXPIRED: Validation failed
   EXPIRED --> RENEWING: Run renewal macro (if set)
   RENEWING --> VALID: Macro succeeded + re-validate OK
   RENEWING --> EXPIRED: Macro failed (retry)
   EXPIRED --> ERROR: 3 consecutive failures

• burp/BurpExtender: Bootstrap; registers ITab and listeners
• controller/HttpListener: Intercepts proxy/http messages
• controller/RequestController: Core analyzer (mutations, send, analyze)
• entities/*: Session, Token, AnalyzerRequestResponse, ValidationConfig, RenewalMacro
• filter/*: InScope, OnlyProxy, FileType, Method, StatusCode, Path, Query
• gui/main/*: SessionPanel, SessionMonitorPanel, CenterPanel
• util/*: CurrentConfig, RequestModifHelper, ExtractionHelper, SessionValidationManager, SessionMacroExecutor

• Burp Suite (Community or Professional)
• Java 8 runtime
• Maven 3.x

cd auth-analyzer
make build    # wraps: mvn clean package
# Output: target/AuthAnalyzer-1.1.15-jar-with-dependencies.jar

1. Burp → Extender → Extensions → Add
2. Type: Java
3. Select: target/AuthAnalyzer-1.1.15-jar-with-dependencies.jar
4. Confirm startup message: "SessionGuard Analyzer successfully started"

1. Create one session per user role (e.g., Admin, User)
2. Add session headers or cookies to replace
3. Define tokens (e.g., SESSIONID, csrfToken) and extraction methods
4. Optionally enable Session Monitoring with a validation URL Caption: Creating sessions, adding headers/tokens, enabling monitoring.

Represent a user role with distinct headers (cookies, authorization) and tokens. Sessions can be cloned and scoped to URLs.

Define values that SessionGuard extracts from responses and injects into subsequent requests. Examples: cookies, CSRF, JWT, custom IDs.

• Auto Extract (Set-Cookie, HTML input fields, JSON keys)
• From-To String (custom delimiters)
• Static Value (constant)
• Prompt for Input (e.g., 2FA codes)

Replace in path, query, cookies, headers, form body, or JSON body. Support for removing parameters to test negative paths.

Heuristics classify results as:

• SAME: Bodies (and optionally status) match
• SIMILAR: Status matches and body length within threshold (±5% default)
• DIFFERENT: Everything else

Caption: Analyzer controls, session list, filters, and results table.

Caption: Define headers, tokens, extraction rules, and scope.

Caption: Configure validation URL, expected status, macro selection, and view status chips.

Caption: Status (SAME/SIMILAR/DIFFERENT), filters, and export options.

Extracts when a response contains:

• Set-Cookie: <name>=<value>
• HTML <input name="<name>" value="...">
• JSON { "<name>": "value" }

Caption: Auto extract locations configuration.

Use for constants like static CSRF tokens, usernames, etc.

Supported insertion points:

• Path segments (e.g., /api/user/99 → replace 99)
• URL query parameters
• Cookies
• Form-URL-Encoded or Multipart body
• JSON body keys

Caption: Choose where a token should be replaced.

Remove selected parameters/headers.

Configure a periodic health check per session:

• Method, URL, headers, body
• Success criteria: status code, body substring, or regex

Define named, multi-step HTTP flows to renew expired sessions (e.g., login sequence). Steps can extract tokens from responses.

Use dynamic placeholders replaced at runtime with current token values:

POST /rest/user/login HTTP/1.1
Host: localhost:3000
Content-Length: 48
Connection: keep-alive

{"email":"[[email]]","password":"[[password]]"}

Caption: Macro steps with headers, body, and placeholders.

States: UNKNOWN → VALID → (EXPIRED ↔ RENEWING) → ERROR (after 3 failed renewals)

After 3 consecutive renewal failures, SessionGuard displays a dialog with the failing macro and reason, and pauses further attempts.

• Auto extract session cookie during login and reuse across requests
• Session header + CSRF token handling with auto-extract
• Extract token from JavaScript variable via From-To
• Auto extract and insert Bearer tokens in Authorization header
• Test several roles in parallel by cloning sessions
• Refresh auto-extracted values via Renew or by replaying a request
• Test idempotent operations by dropping original requests
• Test anonymous sessions by removing auth headers
• Validate CORS by adding Origin and switching to OPTIONS
• Test CSRF protections by removing token parameters
• Verify bypass status via Compare and Diff views

• Concurrency control via thread pool (auto-serializes when prompting for input)
• Tunable similarity threshold for SIMILAR classification
• Export results as HTML or XML for reporting
• Auto-save configuration; load/save setups to file

Validation fails immediately
Check URL, status/regex criteria, and session headers.

Renewal macro does not refresh tokens
Verify step URLs, headers, body; ensure placeholders map to defined tokens; check Burp Extender Output for errors.

Bypass statuses look unexpected
Adjust similarity threshold; compare responses via Diff to understand differences.

Prompt for Input blocks concurrency
This is by design when prompts are active. Disable prompting or pre-populate values.

No results appear
Confirm filters (scope/method/filetype) don’t exclude traffic; ensure you are browsing through Burp.

• Entry point: src/burp/BurpExtender.java
• Core flow: controller/HttpListener → util/CurrentConfig.performAuthAnalyzerRequest(...) → controller/RequestController.analyze(...)
• Add new filters under filter/ and register via CurrentConfig
• Extend ExtractionHelper for new token sources
• Modify RequestModifHelper for new insertion points
• Bypass heuristics in RequestController.analyzeResponse(...)
• Session monitoring: SessionValidationManager + SessionMacroExecutor

• Session creation, renaming, removal, and cloning
• Unlimited headers to replace/add; headers to remove
• Unlimited parameters to replace with multiple extraction methods
• Parameter removal for negative testing
• Detailed per-session status panel with validation/renewal
• Request replay via context menu
• Table filters, search, and export

This project is licensed under the MIT License. See LICENSE for details.

• Start/Stop controls for the analyzer
• Scope restriction and duplicate header filtering
• Auto-save, load/save configuration

• Start/Stop Analyzer: Cmd/Ctrl + R
• Toggle Filters: Cmd/Ctrl + F
• Show Diff View: Cmd/Ctrl + D
• Export Results: Cmd/Ctrl + E

Configurations are persisted via the built-in storage provider. Exported files include sessions, headers, tokens, and monitoring settings. See util/DataStorageProvider for details.

This example demonstrates setting up automatic session validation and renewal for a typical authenticated web application.

• Burp Suite with Auth Analyzer extension loaded
• A target application with login functionality
• Session cookies or authentication tokens that can expire

1. In the Auth Analyzer tab, click Add Session (the "+" icon)
2. Name your session (e.g., "Low Privilege User")
3. In Header(s) to Replace, add the session cookie header:

   Cookie: SESSIONID=placeholder
   

4. Add a parameter for automatic token extraction:
   • Parameter Name: SESSIONID
   • Extraction Method: Auto Extract
   • Extract Location: Set-Cookie Header (click settings icon to configure)
   • Replace Location: Cookie Parameter

1. Click the Session Monitoring button in your session panel
2. Fill in the validation configuration:
   • Enable Session Monitoring: ✓ (checked)
   • Target URL: https://target.app/health (or any authenticated endpoint)
   • Request Method: GET
   • Expected Status: 200
   • Response must contain: success (or use regex)
3. Leave Renewal Macro as "None" for now (we'll create it next)

1. Navigate to the Session Monitor tab
2. In the Renewal Macros tab, click Add Macro
3. Configure the macro:
   • Name: Login Flow
   • Description: Performs login and obtains fresh session
4. Click Add Step and configure the login request:
   • Method: POST
   • URL: https://target.app/login
   • Headers:

     Content-Type: application/x-www-form-urlencoded
     

   • Body:

     username=testuser&password=testpass123
     

5. Click Save Step, then Save Macro

1. Return to the Analyzer tab
2. Click Session Monitoring on your session again
3. In the Renewal Macro dropdown, select Login Flow
4. Click Save

1. Start the Auth Analyzer (click ▶ Start)
2. Browse the target application with a high-privilege user in your browser
3. Watch the Session Monitor → Session Status tab:
   • Validation checks run every 60 seconds
   • Status shows VALID, EXPIRED, ERROR, or UNKNOWN
   • Last check time and message are displayed
4. To simulate expiration:
   • Manually invalidate the session cookie in your browser
   • Wait for the next validation check
   • Watch the macro execute automatically and renew the session

1. In the Analyzer tab, view the request/response table
2. Filter by bypass status:
   • SAME: Response identical to original (potential bypass)
   • SIMILAR: Response similar in size/status (investigate)
   • DIFFERENT: Access denied (expected)
3. Use Compare View and Show Diff to analyze differences
4. Export results to HTML/XML for reporting

For dynamic values in renewal macros, use placeholders:

• [[tokenName]]: Replaced with current token value
• Example in macro body: &user=[[username]]
• Tokens must be defined in the session's parameter list

• Validation fails immediately: Check target URL, expected status, and response criteria
• Macro doesn't renew: Verify macro steps (URL, headers, body), check Burp's Output tab for errors
• After 3 failures: A dialog appears; fix the macro or validation config and restart the analyzer