AuthenticationAgent

Specialized agent for automated authentication and session management

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 · 'captcha' | 'mfa' | 'oauth_consent' | 'rate_limit' | 'invite_code' | 'admin_approval' | 'email_verification' | 'phone_verification' | 'unknown'

Type of barrier encountered

details · string

Details about the barrier

loginUrl · string

Login URL where the barrier was encountered

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: "[e-mail]",
      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: "[e-mail]",
      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: "[e-mail]",
  password: "admin_password",
  loginUrl: "https://example.com/login",
  role: "admin",
});

credentialManager.addCredential({
  id: "user_creds",
  username: "[e-mail]",
  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}`);
}

Token Verification (No Login Flow)

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: "[e-mail]",
      password: "password123",
      loginUrl: "https://example.com/login",
    },
    emailIntegration: {
      provider: "imap",
      inboxes: [
        {
          email: "[e-mail]",
          imapHost: "imap.gmail.com",
          imapPort: 993,
          username: "[e-mail]",
          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

Traditional HTML form login:

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

JSON API Auth

JSON-based authentication:

authCredentials: {
  username: "[e-mail]",
  password: "password",
  loginUrl: "https://api.example.com/auth/login",
}

Bearer Token

Token verification and usage:

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

API Key

API key authentication:

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

OAuth

OAuth flows (requires browser):

authCredentials: {
  username: "[e-mail]",
  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.

Related

• OffensiveSecurityAgent
• BlackboxAttackSurfaceAgent
• TargetedPentestAgent