Credential Checking with KeyCheck

Build a robust login checker pipeline using KeyCheck blocks for accurate result classification

The KeyCheck block is the heart of credential validation in IronBullet. It evaluates conditions against response data to classify each check as Success, Fail, Ban, Retry, or Custom.

How KeyCheck Works

KeyCheck contains multiple keychains. Each keychain has:

• A result (Success/Fail/Ban/Retry/Custom)
• One or more conditions
• A mode (AND/OR)

Keychains are evaluated top-to-bottom. The first keychain where all conditions match (AND mode) or any condition matches (OR mode) sets the bot status and stops evaluation.

1. Set Up Your Pipeline

   Create a new pipeline with these blocks:

   1. HttpRequest - send login request
   2. ParseJSON - extract data (optional)
   3. KeyCheck - classify the result

   This is the standard credential checking pattern.

2. Configure the HTTP Request

   Set up your login endpoint:

   Method: POST
   URL: https://api.example.com/auth/login
   Headers:
     Content-Type: application/json
   Body:
     {"username":"<input.USER>","password":"<input.PASS>"}
   

   The response is automatically stored in data.SOURCE and data.RESPONSECODE.

3. Create Success Keychain

   In the KeyCheck block, add your first keychain:

   Result: Success
   Mode: AND
   

   Add conditions that indicate a successful login. Common patterns:

   Pattern 1: Status Code Check

   Source: data.RESPONSECODE
   Comparison: EqualTo
   Value: 200
   

   Pattern 2: Response Contains Token

   Source: data.SOURCE
   Comparison: Contains
   Value: "access_token"
   

   Pattern 3: Specific JSON Field

   Source: data.SOURCE
   Comparison: Contains
   Value: "\"success\":true"
   

   Use AND mode when ALL conditions must be true.

4. Create Fail Keychain

   Add a second keychain for failed logins:

   Result: Fail
   Mode: OR
   

   Common failure indicators:

   Invalid Credentials

   Source: data.SOURCE
   Comparison: Contains
   Value: "Invalid username or password"
   

   401 Unauthorized

   Source: data.RESPONSECODE
   Comparison: EqualTo
   Value: 401
   

   Wrong Password

   Source: data.SOURCE
   Comparison: Contains
   Value: "incorrect password"
   

   Use OR mode so any failure message triggers a Fail.

5. Handle Bans and Rate Limits

   Add keychains for ban detection (should be BEFORE Fail):

   Result: Ban
   Mode: OR
   

   Conditions:

   Source: data.RESPONSECODE
   Comparison: EqualTo
   Value: 429
   

   Source: data.SOURCE
   Comparison: Contains
   Value: "Too many requests"
   

   Source: data.SOURCE
   Comparison: Contains
   Value: "rate limit"
   

   When a check is marked as Ban:

   • The proxy (if used) is temporarily banned
   • The data line is re-queued with a different proxy
   • Helps avoid burning through your entire proxy pool
6. Add Retry for Timeouts

   Add a Retry keychain for temporary errors:

   Result: Retry
   Mode: OR
   

   Conditions:

   Source: data.RESPONSECODE
   Comparison: EqualTo
   Value: 0
   

   (Response code 0 means connection timeout)

   Source: data.RESPONSECODE
   Comparison: EqualTo
   Value: 502
   

   (Bad Gateway - server temporarily down)

   Retry entries are re-queued up to max_retries times (set in Runner settings).

7. Test Your KeyCheck Logic

   Press F5 to debug with test credentials.

   Try different scenarios:

   • Valid login
   • Invalid password
   • Rate limit response (if you can trigger it)
   • Timeout (by using an unreachable URL)

   Check the Result in the debug panel matches your expectations.

Real-World Example: Multi-Step Login

Some sites return different responses for “user doesn’t exist” vs “wrong password”. Here’s how to capture both:

Pipeline:
  1. HttpRequest (POST /login)
  2. KeyCheck

KeyCheck Keychains:
  1. Success (AND)
     - data.SOURCE Contains "dashboard"
     - data.RESPONSECODE EqualTo 200

  2. Custom "2FA Required" (AND)
     - data.SOURCE Contains "verification_code"
     - data.RESPONSECODE EqualTo 200

  3. Fail "Invalid User" (OR)
     - data.SOURCE Contains "user not found"
     - data.SOURCE Contains "email does not exist"

  4. Fail "Wrong Password" (OR)
     - data.SOURCE Contains "incorrect password"
     - data.SOURCE Contains "invalid credentials"

  5. Ban (OR)
     - data.RESPONSECODE EqualTo 429
     - data.SOURCE Contains "captcha"

  6. Retry (OR)
     - data.RESPONSECODE EqualTo 0
     - data.RESPONSECODE EqualTo 502

Advanced: Using Parsed Variables

Combine ParseJSON with KeyCheck for precise checks:

1. HttpRequest (POST /api/auth)
2. ParseJSON
   - JSON Path: status
   - Output Variable: AUTH_STATUS
   - Capture: false

3. ParseJSON
   - JSON Path: user.role
   - Output Variable: USER_ROLE
   - Capture: true

4. KeyCheck
   - Keychain 1 (Success AND):
       * AUTH_STATUS EqualTo "authenticated"
       * USER_ROLE NotEqualTo "banned"

Now your Success hits will include the user’s role:

[e-mail]:password123 | USER_ROLE=administrator

Comparison Operators

Operator	Use Case
Contains	Check if response contains a substring
NotContains	Response must NOT contain substring
EqualTo	Exact match (case-sensitive)
NotEqualTo	Must not match
MatchesRegex	Advanced pattern matching
GreaterThan	Numeric comparison
LessThan	Numeric comparison
Exists	Variable is defined
NotExists	Variable is undefined

Tips

Order matters! Place more specific keychains (Success, Custom, Ban) BEFORE generic ones (Fail, Retry).

If NO keychain matches, the status remains None and the entry is marked as an error. Always add a catch-all Fail keychain at the end.

Use data.ADDRESS to check the final URL after redirects. Useful for detecting login redirects vs error pages.

Debugging KeyCheck Issues

1. All entries show as Error

   • No keychain matched → add a catch-all Fail keychain
   • Check your condition values for typos

2. Success/Fail reversed

   • Check keychain order (Success before Fail)
   • Verify your condition logic (AND vs OR)

3. Random failures on valid combos

   • Add Ban detection for rate limits
   • Lower thread count to reduce request rate
   • Enable proxy rotation

Next Steps

Working with Proxies

Add proxy rotation to avoid bans

Browser Automation

Handle Cloudflare and JavaScript-rendered responses