Define Authentication

Many vulnerabilities exist behind login walls. When creating an Authenticated (Gray Box) test, you provide credentials so CodeWall can access protected areas.

Supported credential types

Bearer token

Use for APIs that authenticate via a static token or JWT.

1. In step 3 (Authentication) of the new pentest wizard, select Bearer Token
2. Enter the token value
3. CodeWall sends it as Authorization: Bearer <token> with every request

Basic auth

Use for applications or APIs that use username/password authentication.

1. Select Basic Auth
2. Enter the username and password
3. CodeWall encodes and sends it as a standard Authorization: Basic header

Custom headers

Use for non-standard authentication mechanisms (API keys, tenant IDs, etc.).

1. Select Custom Headers
2. Add one or more key-value pairs (e.g., X-API-Key: your-key)
3. CodeWall includes all custom headers with every request

Browser session

Use for applications where credentials alone are not enough — for example, targets behind SSO, MFA, CAPTCHAs, or complex multi-step login flows that cannot be replayed with a static token.

Instead of entering credentials manually, you log into the target in your own browser and the Codewall extension captures your authenticated session cookies. The agent then uses those cookies to test as a logged-in user.

When to use browser sessions

Browser session capture is the right choice when:

• The application uses SSO (SAML, OIDC) and there is no way to obtain a standalone token
• Login requires multi-factor authentication (MFA) that cannot be bypassed with a static credential
• The application uses CAPTCHA or bot-detection on its login page
• The login flow involves multiple redirects or interactive steps that the agent cannot automate
• You want to test as a specific real user with their exact permission set and session state

For simpler setups (API key, static JWT, username/password), use one of the other credential types instead — they are easier to configure and do not require the browser extension.

Prerequisites

You need the Codewall Session Capture browser extension installed. It is available for Chrome, Edge, and Firefox. The extension is dormant by default — it only activates when you initiate a capture from the CodeWall dashboard. No background tracking occurs.

How it works

1. In step 3 (Authentication) of the new pentest wizard, select Browser Session
2. Click Capture session — this opens a modal and launches the target URL in a new tab
3. Log into the application normally in that tab (SSO, MFA, CAPTCHA — whatever the login flow requires)
4. Once logged in, click the Codewall extension icon in your browser toolbar, then click Capture Session
5. The extension reads the session cookies for the target origin and securely transmits them to CodeWall
6. Back in the wizard, you will see a confirmation that the session was captured

The captured session has a time-limited window — complete the capture before it expires (shown as a countdown in the modal).

Tips and best practices

• Use a long-lived session. If your application has a "remember me" or "keep me signed in" option, enable it before capturing. Short-lived sessions may expire before the test completes.
• Capture on the right account. The agent tests with whatever access the captured user has. For broad coverage, capture an account with the permissions you want tested (e.g. admin for maximum surface area, or a regular user for privilege escalation testing).
• Pair with a second credential for privilege escalation. Add a browser session for a high-privilege user and a bearer token or basic auth credential for a low-privilege user. CodeWall will test whether the low-privilege credential can access resources that should be restricted to the captured session.
• Only target-origin cookies are captured. The extension scopes its capture to the domain(s) of the target you configured. Cookies for other sites are never read or transmitted.
• Re-capture if the session expires. If a test fails because the session cookie has expired, click Re-capture on the credential to repeat the flow. Consider scheduling tests shortly after capture for time-sensitive sessions.
• Label your sessions. Give each captured session a descriptive label (e.g. "Admin — prod SSO" or "Regular user — staging") so it is easy to identify in the test configuration and results.

Authorization requirement

Because a browser session represents a real user identity, CodeWall requires explicit authorization before starting the test. After capturing a session, you must check the authorization box confirming that you are permitted to test as that user. This is audit-logged and required by the engagement letter.

Authenticator app (TOTP)

Use for accounts protected by an authenticator-app second factor (Google Authenticator, 1Password, Authy, etc.) — the kind that shows a rotating 6-digit code.

1. Create the credential on the Settings → Credentials page (see Reusable credentials below), choosing TOTP Authenticator
2. Enter the account's setup key (the base32 "secret" or "manual entry key" shown when you set up 2FA on the test account — the same string the QR code encodes)
3. Optionally add the account's username and password if the login is password then code; leave them blank for passwordless/SSO-then-TOTP flows
4. During a test, CodeWall computes the current code at the moment the login form asks for it — no shared device or manual step required

Keep the setup key for a dedicated test account, not a real user's. Anyone with the setup key can generate that account's codes.

Email one-time code (OTP)

Use for logins where the target emails a short numeric code that you type in to complete sign-in.

CodeWall needs to read the inbox of the test login account to retrieve the code. You choose how it gets access (see Mailbox access below), then create the credential on Settings → Credentials choosing Email OTP, with the test account's login username and password.

Email magic link

Use for "passwordless" logins where the target emails a one-time sign-in link instead of a code. Setup is identical to Email OTP (choose Email Magic Link) — CodeWall retrieves the link from the test mailbox and opens it once, in the same browser session, to complete login.

Mailbox access (for Email OTP / magic link)

Email-based logins require CodeWall to read the test account's mail. There are two options, chosen per credential:

• CodeWall inbox (recommended) — CodeWall provisions a unique receiving address for this credential (shown once when you save it). Set the email address on the target's test account to that address. You run no mail infrastructure; each credential gets its own isolated address.
• Your IMAP mailbox — provide IMAP host, port, and the username + password (or app-specific password) for a dedicated test mailbox you control. Use a throwaway/test mailbox, never a real person's inbox. Optional sender/subject filters narrow which messages are considered.

In both cases CodeWall only ever reads messages that arrive after, and as a result of, its own login attempt (scoped by time and sender/subject) — it does not read pre-existing mail or mail from other tests. Retrieved codes and links are never written into findings or reports.

Reusable credentials (Settings → Credentials)

Bearer token, basic auth, and custom headers can be entered inline in the test wizard. TOTP, Email OTP, and Email Magic Link are created and stored on the Settings → Credentials page instead, then attached to a test:

1. Go to Settings → Credentials, pick the project, and Add Credential
2. For a CodeWall-inbox email credential, copy the provisioned …@codewall.email address shown after saving and set the target test account's email to it (it is shown only once)
3. In the new pentest wizard, step 3 (Authentication), choose Saved Credential and select it from the list

Saved credentials are reusable across tests, project-scoped, and can be revoked at any time from the same page. Revoking stops a credential being attachable and (for CodeWall-inbox credentials) stops its address receiving further mail.

Multiple credentials

You can add multiple credentials to a single test. This is useful for:

• Testing multiple accounts at different privilege levels
• Providing both authentication and tenant identification headers
• Combining API keys with other custom headers
• Mixing credential types (e.g. a browser session for one account and a bearer token for another)

Testing for privilege escalation

To test whether a lower-privilege account can access higher-privilege resources:

1. Add a low-privilege credential (regular user token)
2. Add a high-privilege credential (admin token or captured browser session)
3. CodeWall will test whether resources accessible with admin credentials can also be reached with the regular user token

Credential security

• Credentials are encrypted at rest and in transit
• They are used only during the active test
• Access to credentials is restricted to organization admins
• Browser session cookies are stored with the same encryption as other credential types and are automatically purged after the test completes
• TOTP secrets and mailbox credentials are encrypted at rest and are never shown in prompts, findings, or reports
• For email logins, mailbox reads are scoped to the test's own login attempt and are audit-logged; CodeWall-inbox messages are encrypted, deleted once used, and purged after a short retention window