Documentation

Everything you need to know about using BattleTester

Before you start

Scans interact with your live app. To find issues, BattleTester logs in and explores your site like a real user. It will likely create test data, and with admin credentials it can trigger actions like editing or deleting records. Run it against an environment you can restore, or sign in with a throwaway account whose data you don't mind touching.

Using Lovable, Replit, Base44, Vercel, or similar? Clone or fork your project first and give BattleTester the cloned or preview URL. That way the scan runs against a copy and your live data stays untouched.

Pointing it at production also means agreeing you have permission to test that site.

What is BattleTester?

BattleTester is an automated security testing platform that helps you identify vulnerabilities in your web applications. It performs comprehensive penetration testing and provides detailed reports with actionable recommendations.

Important: BattleTester should complement, not replace, professional security audits. Always follow up critical findings with manual verification.

Getting Started

Three steps to configure and launch your first scan.

1. Configure Roles

You can choose how BattleTester handles login: provide your own credentials, use automatic registration, or skip login entirely. The choice affects how comprehensive the tests are.

Custom Roles (provide credentials)

Recommended

You supply role names and email/password for each role (e.g. admin, user). BattleTester uses these to log in and test with different permission levels. Best: two roles with different privileges (e.g. admin and user). If that's not possible, two different roles is still better than one.

Best option. Use this when your app has login. Provide at least two roles with different privilege levels (e.g. Admin and User) for thorough testing of authorization and privilege escalation.

For each role: Role name (admin, user, manager, etc.) and Email & password.

Default Credentials (automatic)

Automatic

BattleTester registers test accounts and uses them to crawl and test. No credentials from you.

May miss important tests. Without admin (or other privileged) credentials we cannot test privilege escalation or admin-only endpoints. Use Custom Roles when you can for more comprehensive results.

Registration can fail if your site has any of the following:

CAPTCHA on the registration or login page
Two-factor authentication (2FA / MFA)
Email confirmation required before login
Invite-only or closed registration

No Login Required

Public sites only

The scanner does not log in. Only publicly accessible endpoints are tested.

Only for sites that have no login. If your app has authentication, do not use this. Tests will not be comprehensive and many auth-related checks (e.g. access control, privilege escalation) will be limited or skipped.

2. Select Security Tests

Choose which vulnerability tests to run. Each test targets specific security weaknesses. The colored bar shows its relative severity.

Broken Access Control

(OWASP #1)

Tests if users can access resources or perform actions beyond their permissions. Attempts to access admin endpoints with user credentials, manipulate IDs to access other users' data, and bypass authorization checks.

Example: Regular user accessing /admin/users or viewing another user's profile

SQL Injection

Injects malicious SQL code into input fields to test if database queries are properly sanitized. Can lead to data theft, deletion, or complete database compromise.

Example: Entering ' OR '1'='1 in search field

Cross-Site Scripting (XSS)

Tests if malicious JavaScript can be injected into pages. XSS allows attackers to steal session cookies, redirect users, or modify page content. Tests reflected, stored, and DOM-based XSS.

Example: Injecting <script>alert(1)</script> in form fields

Server-Side Request Forgery (SSRF)

Tests if your server can be tricked into making requests to internal resources or external systems. Can expose internal APIs, cloud metadata endpoints, or internal network services.

Example: Making server request http://localhost:8080/admin

Open Redirect

Tests if URL parameters can be manipulated to redirect users to external attacker-controlled sites. Often used in phishing attacks or to bypass referrer-based security checks.

Example: ?redirect=https://evil.com silently forwards the user

JWT Token Security

Analyzes JSON Web Tokens for weak signing algorithms (none, HS256 with weak secrets), missing expiration claims, and improper validation. Tests token tampering and algorithm confusion attacks.

Tests: Algorithm security, signature validation, expiration, claims

Business Logic Flaws

Tests application-specific logic vulnerabilities like price manipulation, race conditions, workflow bypasses, and parameter tampering. These flaws are unique to your application's business rules.

Example: Negative quantities in cart, coupon reuse, payment amount manipulation

Configuration Checks

A grouped set of checks targeting common misconfiguration vulnerabilities:

SSL/TLS: Weak ciphers, outdated protocols (TLS 1.0/1.1), invalid certificates, missing HSTS headers
Vulnerable Dependencies: Frontend libraries and frameworks with known CVEs
CORS Misconfiguration: Overly permissive cross-origin resource sharing policies
Sensitive Data Exposure: Secrets, API keys, or credentials leaked in client-side source files
Security Headers: Missing or misconfigured headers such as CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, and Permissions-Policy

Rate Limiting

Tests whether endpoints enforce rate limiting. Missing rate limits allow attackers to brute force credentials, enumerate users, spam actions, or overwhelm the server with repeated requests.

Example: Login endpoint with no limit on failed attempts

More tests and configuration checks are added regularly.

3. Verify Site Ownership

Before running a scan, you must prove you own the target website. This prevents unauthorized security testing and ensures legal compliance.

⚠️ Required: You cannot start a scan without verifying ownership

Attempting to scan a site you don't own is illegal and violates our Terms of Service.

Two verification methods:

Option 1: Meta Tag (Recommended)

Add a verification meta tag to your website's HTML <head> section:

<meta name="battletester-verification" content="your-user-id" />

The meta tag will be provided on the scan page. Works with any website or CMS.

Option 2: File Upload

Download the verification file and upload it to your website's root directory:

https://your-site.com/battletester-verification-[user-id].txt

File must be publicly accessible. Useful if you can't modify HTML directly.

Note: Verification is checked each time you start a scan. Keep the meta tag or file on your site for future scans.

Scanner IP Whitelisting

⚠️ Important: Prevent scan failures by whitelisting our IP

If your website has a firewall (WAF), rate limiting, CAPTCHA, or IP blocking, you must whitelist our scanner IP to ensure successful testing.

The scanner IP address is displayed on the "New Scan" page before starting a scan. Common platforms where you might need to whitelist:

Cloudflare: Firewall → Tools → IP Access Rules → Allow our IP
AWS WAF: Create or update IP Set with our scanner IP
CAPTCHA Services: Configure to bypass CAPTCHA for our IP
Rate Limiting: Exclude our IP from rate limits
Server Firewall: Add allow rule in Nginx, Apache, or server config

Without whitelisting, the scanner may be blocked, receive CAPTCHA challenges, or be rate-limited, resulting in incomplete or failed scans.

Troubleshooting

How long do scans take?

Small sites: 30-40 minutes typically
Larger sites: 1-2 hours or more depending on endpoints discovered

Duration depends on application size, number of endpoints, authentication complexity, and selected tests.

Maximum runtime: Scans are automatically aborted after 3 hours. Partial results up to that point are preserved.

Why is my scan pending for so long?

BattleTester currently operates on a queue system. When you see "pending" status, your scan is waiting in the queue for an available scanner.

Queue times vary based on current usage. Your scan will automatically start when a scanner becomes available.

What happens if I abort a scan?

A scan can be aborted manually or automatically after 3 hours. In both cases, aborted scans cannot be resumed. If you need to run the same configuration again:

Go to the aborted scan page
Click the "Duplicate" button
Start a new scan with the same settings

Partial results from aborted scans are preserved and can be viewed.

Need Help?

Can't find what you're looking for or need assistance with your scan?

info@battletester.app