AuthenticationAgent

Overview

The AuthenticationAgent is an authentication-focused specialization of the OffensiveSecurityAgent that handles automated authentication flows. It detects authentication schemes, logs in with provided credentials, manages sessions, and exports authentication state for other agents. Credentials are managed automatically via the session’s CredentialManager — the agent never sees raw secrets. The credential manager is provisioned automatically when you create a session with authCredentials.

Key Features

Automatic Scheme Detection: Detects form-based, JSON, Basic Auth, Bearer, OAuth, and API key authentication
Credential Security: Uses CredentialManager to resolve credentials without exposing secrets to the model
Browser Automation: Handles SPAs, OAuth flows, CAPTCHA, and MFA with browser tools
Session Export: Exports cookies and headers for use by other agents
Email Integration: Supports email-based verification flows (OTP, magic links)
Flow Documentation: Documents auth flows for future runs

Constructor

new AuthenticationAgent(opts: AuthenticationAgentInput)

opts

AuthenticationAgentInput

required

Configuration object for the authentication agent

AuthenticationAgentInput

target

string

required

The target requiring authentication (URL or domain)

model

AIModel

required

AI model identifier (e.g., "claude-sonnet-4-20250514")

session

SessionInfo

required

Session that provides paths and, when created with authCredentials, an auto-provisioned CredentialManager

authHints

AuthHints

Hints about the auth flow from reconnaissance

authScheme

string

Detected authentication scheme (e.g., “form”, “bearer”, “oauth”)

csrfRequired

boolean

Whether CSRF protection was detected

browserRequired

boolean

Whether browser automation may be needed

protectedEndpoints

string[]

List of endpoints that require authentication (for verification)

authConfig

AIAuthConfig

Optional per-provider API key overrides

onStepFinish

StreamTextOnStepFinishCallback<ToolSet>

Optional callback after each agent step

abortSignal

AbortSignal

AbortSignal to cancel mid-run

callbacks

ConsumeCallbacks

Optional persistence callbacks for external storage integration

Result Type

The consume() method returns an AuthenticationResult:

success

boolean

Whether authentication was successful

summary

string

Summary of the authentication process

exportedCookies

string

Exported cookies from the authentication process (e.g., “session_id=abc123; token=xyz789”)

exportedHeaders

Record<string, string>

Exported headers from the authentication process (e.g., Authorization, X-API-Key)

strategy

string

Strategy used for authentication (e.g., “form_post”, “bearer_token”, “oauth”)

authBarrier

AuthBarrier | undefined

Authentication barrier encountered, if any

type

Type of barrier encountered

details

string

Details about the barrier

authDataPath

string

Path to the persisted auth data file (inside session auth/ directory)

Active Tools

The AuthenticationAgent uses the following tools:

execute_command - Run authentication-related commands
authenticate_session - Attempt authentication with credentials
complete_authentication - Mark authentication complete and export session data
browser_navigate - Navigate to login pages
browser_snapshot - Inspect login forms and page structure
browser_screenshot - Capture screenshots for documentation
browser_click - Click login buttons and links
browser_fill - Fill username/password fields (with secure credential resolution)
browser_evaluate - Execute JavaScript for SPA interactions
browser_console - Access browser console for debugging
browser_get_cookies - Extract cookies after successful login
email_list_inboxes - List available email inboxes (if configured)
email_list_messages - List messages for verification codes
email_search_messages - Search for specific verification emails
email_get_message - Retrieve verification codes or magic links

Usage Examples

Basic Authentication

import { AuthenticationAgent } from "@pensar/apex";
import { createSession } from "@pensar/apex/session";

const session = await createSession({
  name: "Auth Test",
  targets: ["https://example.com"],
  config: {
    authCredentials: {
      username: "[email protected]",
      password: "secure_password",
      loginUrl: "https://example.com/login",
    },
  },
});

const agent = new AuthenticationAgent({
  target: "https://example.com",
  model: "claude-sonnet-4-20250514",
  session, // credential manager is auto-provisioned
});

const { success, summary, exportedCookies, exportedHeaders } = await agent.consume({
  onTextDelta: (delta) => {
    process.stdout.write(delta.text);
  },
});

if (success) {
  console.log(`\n✓ Authentication succeeded: ${summary}`);
  console.log(`Cookies: ${exportedCookies}`);
  console.log(`Headers: ${JSON.stringify(exportedHeaders, null, 2)}`);
} else {
  console.log(`\n✗ Authentication failed: ${summary}`);
}

With Authentication Hints

import { AuthenticationAgent } from "@pensar/apex";
import { createSession } from "@pensar/apex/session";

const session = await createSession({
  name: "Hinted Auth",
  targets: ["https://api.example.com"],
  config: {
    authCredentials: {
      username: "[email protected]",
      password: "password123",
      loginUrl: "https://api.example.com/auth/login",
    },
  },
});

const agent = new AuthenticationAgent({
  target: "https://api.example.com",
  model: "claude-sonnet-4-20250514",
  session,
  authHints: {
    authScheme: "bearer",
    csrfRequired: true,
    browserRequired: false,
    protectedEndpoints: [
      "https://api.example.com/api/user",
      "https://api.example.com/api/admin",
    ],
  },
});

const result = await agent.consume({
  onTextDelta: (delta) => process.stdout.write(delta.text),
});

Multiple Credentials (Role-Based)

import { AuthenticationAgent } from "@pensar/apex";
import { CredentialManager } from "@pensar/apex/credentials";
import { createSession } from "@pensar/apex/session";

const credentialManager = new CredentialManager();

// Add multiple credentials with different roles
credentialManager.addCredential({
  id: "admin_creds",
  username: "[email protected]",
  password: "admin_password",
  loginUrl: "https://example.com/login",
  role: "admin",
});

credentialManager.addCredential({
  id: "user_creds",
  username: "[email protected]",
  password: "user_password",
  loginUrl: "https://example.com/login",
  role: "user",
});

const session = await createSession({
  name: "Multi-Role Auth",
  targets: ["https://example.com"],
  credentialManager,
});

// Authenticate as admin
const adminAgent = new AuthenticationAgent({
  target: "https://example.com",
  model: "claude-sonnet-4-20250514",
  session,
});

const adminResult = await adminAgent.consume();
if (adminResult.success) {
  console.log(`Admin authenticated: ${adminResult.strategy}`);
}

import { AuthenticationAgent } from "@pensar/apex";
import { createSession } from "@pensar/apex/session";

const session = await createSession({
  name: "Token Verification",
  targets: ["https://api.example.com"],
  config: {
    authCredentials: {
      // Provide existing tokens for verification
      tokens: {
        bearerToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        customHeaders: {
          "X-API-Key": "secret_key_123",
        },
      },
    },
  },
});

const agent = new AuthenticationAgent({
  target: "https://api.example.com",
  model: "claude-sonnet-4-20250514",
  session,
  authHints: {
    protectedEndpoints: ["https://api.example.com/api/user"],
  },
});

const result = await agent.consume();

if (result.success) {
  console.log("Tokens are valid and grant access");
} else {
  console.log("Tokens are invalid or expired");
}

With Email Integration (MFA/OTP)

import { AuthenticationAgent } from "@pensar/apex";
import { createSession } from "@pensar/apex/session";

const session = await createSession({
  name: "MFA Auth",
  targets: ["https://example.com"],
  config: {
    authCredentials: {
      username: "[email protected]",
      password: "password123",
      loginUrl: "https://example.com/login",
    },
    emailIntegration: {
      provider: "imap",
      inboxes: [
        {
          email: "[email protected]",
          imapHost: "imap.gmail.com",
          imapPort: 993,
          username: "[email protected]",
          password: "email_app_password",
        },
      ],
    },
  },
});

const agent = new AuthenticationAgent({
  target: "https://example.com",
  model: "claude-sonnet-4-20250514",
  session,
  authHints: {
    authScheme: "form",
    browserRequired: true,
  },
});

const result = await agent.consume({
  onTextDelta: (delta) => process.stdout.write(delta.text),
});

// Agent will automatically:
// 1. Fill login form
// 2. Wait for MFA prompt
// 3. Check email inbox for OTP code
// 4. Enter OTP code
// 5. Complete authentication

Using Exported Auth in Other Agents

import { AuthenticationAgent, TargetedPentestAgent } from "@pensar/apex";
import { createSession } from "@pensar/apex/session";
import { writeFileSync, mkdirSync } from "fs";
import { join } from "path";

const session = await createSession({
  name: "Full Test",
  targets: ["https://example.com"],
  config: {
    authCredentials: {
      username: "admin",
      password: "password",
      loginUrl: "https://example.com/login",
    },
  },
});

// Step 1: Authenticate
const authAgent = new AuthenticationAgent({
  target: "https://example.com",
  model: "claude-sonnet-4-20250514",
  session,
});

const authResult = await authAgent.consume();

if (!authResult.success) {
  throw new Error(`Authentication failed: ${authResult.summary}`);
}

console.log(`✓ Authenticated with ${authResult.strategy}`);

// Step 2: Auth data is automatically persisted to session auth/auth-data.json
// Step 3: Use authenticated session in pentest agent
const pentestAgent = new TargetedPentestAgent({
  target: "https://example.com",
  objectives: ["Test for IDOR on /api/users/{id}"],
  model: "claude-sonnet-4-20250514",
  session, // Automatically uses auth-data.json
});

const pentestResult = await pentestAgent.consume();
console.log(`Found ${pentestResult.findings.length} vulnerabilities`);

Authentication Strategies

The agent supports multiple authentication strategies:

Form-Based Auth
JSON API Auth
Bearer Token
API Key
OAuth

Traditional HTML form login:

authCredentials: {
  username: "admin",
  password: "password",
  loginUrl: "https://example.com/login",
}

JSON-based authentication:

authCredentials: {
  username: "[email protected]",
  password: "password",
  loginUrl: "https://api.example.com/auth/login",
}

Token verification and usage:

authCredentials: {
  tokens: {
    bearerToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  },
}

API key authentication:

authCredentials: {
  tokens: {
    customHeaders: {
      "X-API-Key": "secret_key_123",
    },
  },
}

OAuth flows (requires browser):

authCredentials: {
  username: "[email protected]",
  password: "password",
  loginUrl: "https://example.com/oauth/authorize",
},
authHints: {
  authScheme: "oauth",
  browserRequired: true,
}

Authentication Barriers

The agent detects and reports various authentication barriers:

CAPTCHA: Visual or reCAPTCHA challenges
MFA: Multi-factor authentication (email OTP, SMS, authenticator apps)
OAuth Consent: Third-party OAuth consent screens
Rate Limiting: Login attempt restrictions
Invite Code: Registration requires invitation
Admin Approval: Account requires manual approval
Email Verification: Email verification required before login
Phone Verification: Phone number verification required

Barriers are returned in the authBarrier field of the result.

Persisted Auth Data

Authentication state is persisted to {session.rootPath}/auth/auth-data.json:

{
  "authenticated": true,
  "cookies": "session_id=abc123; token=xyz789",
  "headers": {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "X-API-Key": "secret_key_123"
  },
  "strategy": "bearer_token",
  "authBarrier": null,
  "summary": "Successfully authenticated using bearer token"
}

Other agents (like TargetedPentestAgent) automatically read this file and include the credentials in their requests.

Convenience Runner

import { runAuthenticationAgent } from "@pensar/apex/agents/specialized/authenticationAgent";

const result = await runAuthenticationAgent({
  target: "https://example.com",
  model: "claude-sonnet-4-20250514",
  session,
});

// Automatically logs progress and results to console

Best Practices

Credential Security: Never pass raw passwords to browser tools. Use credentialId + credentialField parameters for secure credential resolution.

Auto-Provisioning: The CredentialManager is automatically provisioned when you create a session with authCredentials. No need to create it manually.

Email Integration: For targets with email-based MFA or magic links, configure emailIntegration in the session config.

Browser Requirement: Some authentication flows (OAuth, CAPTCHA, SPAs) require browser automation. Set authHints.browserRequired: true to prioritize browser tools.

API Overview

Core APIs

Agents

Overview

Key Features

Constructor

AuthenticationAgentInput

Result Type

Active Tools

Usage Examples

Basic Authentication

With Authentication Hints

Multiple Credentials (Role-Based)

With Email Integration (MFA/OTP)

Using Exported Auth in Other Agents

Authentication Strategies

Authentication Barriers

Persisted Auth Data

Convenience Runner

Best Practices

Build docs developers (and LLMs) love

API Overview

Core APIs

Agents

​Overview

​Key Features

​Constructor

​AuthenticationAgentInput

​Result Type

​Active Tools

​Usage Examples

​Basic Authentication

​With Authentication Hints

​Multiple Credentials (Role-Based)

​Token Verification (No Login Flow)

​With Email Integration (MFA/OTP)

​Using Exported Auth in Other Agents

​Authentication Strategies

​Authentication Barriers

​Persisted Auth Data

​Convenience Runner

​Best Practices

​Related

Build docs developers (and LLMs) love

Overview

Key Features

Constructor

AuthenticationAgentInput

Result Type

Active Tools

Usage Examples

Basic Authentication

With Authentication Hints

Multiple Credentials (Role-Based)

Token Verification (No Login Flow)

With Email Integration (MFA/OTP)

Using Exported Auth in Other Agents

Authentication Strategies

Authentication Barriers

Persisted Auth Data

Convenience Runner

Best Practices

Related