Using Macros in BurpSuite
Web application penetration testing often involves tedious and repetitive actions especially when dealing with login sequences, CSRF tokens, and dynamic sessions. Enter macros in BurpSuite, a powerful feature that lets you automate these repetitive tasks and enable automated testing, improving efficiency and consistency.
If you’ve ever wondered why your Burp Intruder attacks fail after a few payloads or why your session token keeps expiring during a scan, the answer usually lies in the absence of a proper macro setup. As a leading tool for web application security testing, Burp Suite offers robust automation capabilities, including session handling, CSRF token management, and more. This guide will show you not only how to use macros in BurpSuite but also why they are essential to a professional web testing workflow.
What Are BurpSuite Macros?
A macro in BurpSuite is an automated sequence of HTTP requests and responses designed to simulate interactions like logging in, retrieving CSRF tokens, or refreshing expired sessions. Burp Suite macros are a feature for automating complex tasks, such as handling CSRF tokens, performing mass assignment fuzzing, and streamlining workflows by automating request sequences. These macros help Burp tools (like Intruder, Repeater, and Scanner) maintain application state during testing.
Unlike writing scripts or plugins, macros are configured within Burp’s GUI using the macro editor. The macro editor allows users to create, configure, and manage macros, making them beginner-friendly yet incredibly powerful.
Why Use Macros in BurpSuite?
Macros solve several persistent problems that testers encounter:
- Session Timeout: Keep your session alive without re-logging manually.
- Dynamic Token Management: Automatically fetch and inject fresh CSRF, JWT, or auth tokens.
- Multi-Step Workflows: Automate chained requests like quote and buy products.
- Authenticated Scans: Ensure Scanner tests authenticated areas without constant interruptions.
- Intruder Efficiency: Avoid 403 errors by refreshing tokens for each payload.
Using macros also helps testers avoid common pitfalls such as session timeouts and token expiration.
In short, macros are important to ensure a thorough test of web applications.
When Do You Actually Need Macros?
You should consider using macros if you’re doing any of the following:
- Testing login-protected pages
- Using forms with anti-CSRF mechanisms
- Working on apps that regenerate tokens or session IDs frequently
- Sending multiple requests through Intruder or Repeater
- Automating workflows with multiple steps (e.g., form submission after login)
- Choosing the right macro setup depending on the attack type, such as brute-force or multi-step attacks
If you’re performing just one-off manual requests, macros may be overkill. But for anything repetitive or dynamic, they’re a lifesaver.
Key Use Cases for BurpSuite Macros
| Use Case | Description |
|---|---|
| Login Automation | Record login requests to auto-authenticate |
| Token Refreshing | Auto-fetch CSRF or Bearer tokens |
| Pre-Test State Setup | Set session state before Repeater/Intruder tests |
| Authenticated Spidering/Scanning | Ensure access to user-only pages |
| Multi-Step Requests | Simulate sequences like checkout processes |
Note: Suite macros streamline these use cases by automating request sequences and session management, making tasks like handling CSRF tokens and mass assignment vulnerability testing more efficient during penetration testing.
How to Create a Macro in BurpSuite
Setting up a macro in Burp Suite involves a few key steps. Here’s how:
- Navigate to Project Options > Sessions > Macros. The sessions tab is where you manage macros and session handling rules.
- Click the add button to create a new macro. This opens the macro recorder and the macro editor, where you can manage and edit macro steps.
- In the macro recorder, select the requests you want to include in the macro from the proxy history (for example, a login POST request, a request to load a blog post to obtain a CSRF token, or any other relevant requests). This sequence will be captured for automation.
- For each request in the macro, use the configure item settings to specify how the request should be handled. You can edit the request body to include dynamic tokens or other values as needed.
- Configure parameters and parameter handling for dynamic values. Set up extraction of request parameters such as CSRF tokens, and define custom parameter extraction if the token is not standard. You can specify a custom parameter location or multiple custom parameter locations (e.g., inside JavaScript or dynamically generated content) to accurately extract tokens. Extract values from a previous response or prior response to maintain interdependent requests. Make sure to update only specific parameters in the requests to avoid overwriting the current request. The cookie jar and session handling cookie jar help maintain session state and valid cookies during macro execution. Always extract a new token for each request to ensure a valid csrf token and avoid invalid token errors. You can use the parameter extractor to automatically extract dynamic values from responses and inject them into subsequent requests.
- When finished, click ok to save the macro configuration. Set up the macro to run a macro as part of session handling rules using the session handling rule editor. In the session handling action editor, add a rule action (or multiple rule actions) such as ‘run a macro’ or ‘run post request macro’ for multi-step workflows. Create a new session handling rule and use the scope tab to define where the macro applies, setting the url scope or a custom scope as needed. Integrate the macro with other tools like Intruder, Repeater, or Scanner. For advanced attack scenarios, configure the macro for an intruder attack using attack types like cluster bomb or brute force.
After saving, use the test macro feature to verify that the macro works as intended and extracts parameters correctly.
Additionally, configure a resource pool or new resource pool to control concurrency, and set maximum concurrent requests to 1 if you are dealing with single-use tokens to prevent token invalidation.
Tip: When using Burp macros, you can efficiently automate complex testing workflows, manage session states, and handle dynamic tokens for robust security testing.
Recording Login Workflows as Macros
Let’s say your target app requires a login before accessing protected pages.
- Go to Burp Proxy > HTTP History
- Right-click on the login request > “Add to Macro”
- When adding the login request, make sure to capture all necessary request headers, such as authentication or CSRF headers (e.g., CSRF-Token, X-CSRF-Token), to ensure the macro works correctly.
- Optionally, include the token request that appears before login
- In Session Handling Rules, set the macro to trigger “before requests to this URL pattern”
- Test it with Intruder or Scanner to confirm auto-login is working
This prevents constant 401 errors and keeps the test authenticated throughout.
Using Macros to Refresh Tokens
Many web apps use short-lived CSRF or JWT tokens. If your Burp request fails after a few minutes, it’s probably due to an expired token.
With a macro:
- Capture the token fetch request – ensure the macro always obtains a new token for each request
- Use the parameter extractor to grab the token from the response
- Set the macro to update headers, body, or cookies in future requests
This is extremely useful for Intruder and Scanner, which would otherwise send outdated tokens. Always make sure each automated request includes a valid csrf token to prevent invalid token errors.
Integrating Macros with Burp Tools
Macros can be linked to almost every major Burp tool:
- Repeater: Automatically re-authenticate or refresh tokens before replay
- Intruder: Fire a macro before each payload to avoid invalid session errors
- Scanner: Ensure scan requests maintain a valid session
- Spider: Crawl authenticated areas smoothly
Macros can also be integrated with other tools within Burp Suite for comprehensive automation.
Macros integrate via Session Handling Rules, which define the when, where, and how of macro execution.
Authenticated Scanning with Macros
Authenticated scanning is where macros truly shine. Scanners typically fail if a login session expires mid-test.
Here’s how to fix that:
- Create a macro with your login steps
- Add a Session Handling Rule to trigger the macro before requests
- Use parameter extraction to inject any dynamic tokens
- Launch a scan on authenticated pages
Note: You can also configure a post request macro in your session handling rules to automate additional verification steps after login, such as checking for admin access or confirming privilege escalation. This helps ensure your scan adapts to complex authentication or authorization workflows.
Burp will automatically re-login as needed no manual babysitting required.
Common Issues and Fixes with Macros
| Issue | Fix |
|---|---|
| Macro doesn’t trigger | Check Session Handling Rule conditions |
| Token not updating | Adjust parameter extraction rules |
| Login fails intermittently | Add delays or wait for redirects in macro |
| Macro loops endlessly | Avoid recursive calls by excluding macro URLs |
| Incorrect request sequencing | Reorder or re-record the request flow |
| Invalid token | Ensure macro fetches a fresh token for each request and session handling rules are correctly configured. |
Always test your macro manually before trusting it in an automated test.
Best Practices for Using BurpSuite Macros
- Name your macros clearly
- Avoid over-recording: Include only essential requests
- Use regex in extractors to capture dynamic values precisely
- Set appropriate scope filters to limit macro execution
- Log macro activity to debug issues quickly
- Always test macro functionality: Run the test macro to verify it performs as intended before deploying it in automated tests
Proper setup saves you from countless hours of frustration during large-scale assessments.
Macros vs Manual Request Replay
Manual replay is fine for one-off checks, but it’s inefficient and error-prone. Macros are:
- Faster
- More consistent
- Capable of handling dynamic workflows
If you’re replaying the same actions more than once, automate them with a macro.
Working with Parameter Extractors
This feature allows you to dynamically update values in your request by extracting them from previous responses. Proper parameter handling is essential for accurate macro execution, as it ensures that parameters such as tokens or session IDs are correctly derived and managed throughout the process. For example:
- Extract a CSRF token from the login response body
- Inject it into the header or body of your next request
Burp offers simple UI-based options and supports regex and JSONPath, making it highly flexible.
How Macros Improve Workflow Automation
Macros eliminate repetitive steps and reduce human error. In larger assessments, this can:
- Save hours of redundant work
- Allow overnight or batch testing
- Ensure consistent test execution
- Simplify complex user interaction flows
- Avoid errors during scanning due to session handling
They’re a fundamental part of scalable and professional pentesting.
Differences Between BurpSuite Pro and Community
While both versions support macros, there are important limitations:
| Feature | BurpSuite Community | BurpSuite Professional |
|---|---|---|
| Macro creation | ✔ | ✔ |
| Session Handling Rules | ❌ | ✔ |
| Intruder + Macro Integration | ❌ | ✔ |
| Scanner + Macro Support | ❌ | ✔ |
For full macro functionality, especially automation with Intruder and Scanner, BurpSuite Pro is essential.
Logging Macro Activity
Monitor and debug macros by:
- Enabling Logger++ Extension
- Checking HTTP History in the Proxy tab
- Reviewing Session Handling Logs for rule matches and macro execution
This helps fine-tune your automation and ensure correct functionality.
Alternative Tools to Burp Macros
While Burp macros work well within the HTTP layer, some scenarios require UI-based automation. That’s where tools like Selenium shine.
Use Selenium when:
- You need to interact with JavaScript-heavy apps
- You want to simulate full browser interactions
- The web app uses complex UI forms or popups
Pairing Selenium with Burp (e.g., running Selenium before a Burp scan) can handle both frontend and backend seamlessly.
How to Decide Between Macros and Scripts
| Choose Macros If… | Choose Scripts If… |
|---|---|
| You’re working with HTTP requests/responses | You need browser-level automation |
| You want quick automation within Burp | You want to control mouse clicks, modals, or DOM logic |
| You’re handling session state or token injection | You’re interacting with client-side JavaScript |
Both tools complement each other. Use the right tool for the right layer.
Real-World Case Study: Authenticated API Testing
A penetration tester working on a healthcare platform encountered issues with API tokens expiring every 5 minutes. Rather than re-generating the token manually, they:
- Created a macro to authenticate via API login
- Configured the macro to extract the Bearer token from the response
- Used Session Handling Rules to update every outgoing API request with the fresh token
The result? A seamless, continuous test that required no manual intervention during a 3-hour test.
Final Thoughts
Using macros in BurpSuite isn’t just a “nice to have” it’s a vital skill for anyone serious about web security testing. Whether you’re running a simple login test or automating advanced API workflows, macros can save time, reduce errors, and expand your testing capabilities.
If you’re not using macros yet, you’re probably missing things due to session handling and timeouts cancelling your scans. Start small record a login macro. Then grow into more advanced use cases like token injection, multi-step workflows, and full authenticated scanning.
FAQs
What are BurpSuite macros used for?
They automate HTTP request sequences, like login or token renewal, to maintain session state during testing. Macros are configured in the sessions tab and managed via the macro editor, where you can set up and edit the sequence of requests.
Can you use macros in the free version of BurpSuite?
Basic macro creation is available, but full automation with Intruder and Scanner needs Burp Pro.
Are Burp macros better than writing scripts?
For HTTP-layer tasks, yes. They’re quicker to set up and integrate directly with BurpSuite tools.
Can macros be triggered conditionally?
Yes, using Session Handling Rules you can define precise triggers for macro execution.
Is it possible to debug Burp macros?
Absolutely. Use HTTP History, Logger++, and Session Handling Logs to see what each macro is doing.
When should I use Selenium instead of macros?
Use Selenium when you need full browser automation, such as handling modals, JS-heavy pages, or clicking buttons.