Prepare your target

To run a pentest, you provide a target and the access the agents need to reach it. All testing stays within the scope you set.

Target URLs

You give one to twenty-five base URLs for the application you want tested, for example https://staging.example.com. Each URL must be distinct. Listing the same host twice would not test it twice, so AISafe tells you about the repeat instead of quietly ignoring it. AISafe checks each URL before the run starts. If a target is unreachable, the run does not start, you see a clear message, and you are not charged. The assessment page then shows Start refused with the name of the target AISafe could not reach, and the page still shows this when you come back to it. Fix the target and press Start again.

Domain ownership

AISafe tests only hosts you control. You prove each host once for your organization, and the proof then covers every project and assessment that tests it. A proof does not expire.

You prove a host with any one of three proofs. The Verify dialog shows them as three tabs:

• CNAME: a CNAME record at your DNS provider. Its name is the record name shown, which starts with _aisafe-verification-, and it points at the value shown, which ends in verify.aisafe.io. The record goes on that verification name, never on the host itself, so it does not change how your site is served. AISafe reads only this one record. It does not look up or connect to the name the record points at, so that name does not need to resolve.
• File: an HTTPS file at the displayed URL, containing only the displayed value.
• TXT: a TXT record at your DNS provider, at the same record name, with the displayed value.

The record name and file name contain a random part, so nobody can look up a fixed name on your domain to learn whether you use AISafe. The record stays the same, so a record you published once keeps working. A proof covers that exact host name; a subdomain needs its own proof, with one exception for black-box pentests, described in the next section.

Hosts your application calls

Many applications are served from one host and call others: a single-page application on app.example.com may load its data from api.example.com or send you to auth.example.com to sign in. For a black-box pentest, every host under a domain your organization has verified is in scope. When your application calls one of those hosts, the agents record and test it like a target, and you do not have to list it separately.

• A proof of example.com covers example.com and everything under it, such as app.example.com, api.example.com and auth.example.com.
• A proof of app.example.com covers app.example.com and every host under it, such as api.app.example.com and x.y.app.example.com. It does not cover example.com or other hosts beside app.example.com, such as api.example.com, because it does not show that you control the rest of example.com.

So if your API is on api.example.com and your application on app.example.com, verify example.com, or verify api.example.com as well. Verify each name the same way as any other host. Add it to Additional allowed domains if you want it tested on its own as well.

A public suffix, the part of a name that anyone can register under, such as com, co.uk or github.io, is never a verified domain. Neither is a name that does not exist on the public internet, such as one ending in .test, .internal or .local.

Hosts outside your verified domains, such as a third-party sign-in provider or a CDN, are never tested. The one exception is a test user's OAuth token URL: AISafe sends the token request to that URL so the test user can sign in, and nothing else on that host. Host exclusions still apply to hosts under a verified domain, and a target URL with a path still limits its own host to that path.

You can prove a project's hosts before you start an assessment. Open the project's Setup, then Targets. Each host shows whether it is verified and, once it is, how and when. Press Verify beside a host to see its CNAME record, its file and its TXT record, publish one of them, and press Check now. If the check does not find the record, the dialog says why, for example that the record was not found yet or that its value does not match.

When you create an assessment, Define test scope and the Additional allowed domains list in Advanced configuration show the same states. A host your organization already proved shows as verified and needs nothing more; every other host has a Verify button that opens the same dialog. You can move on to the next step before you prove a host.

AISafe checks the proof when you start validation. If a host is not proved yet, the assessment waits in validation and shows Waiting for domain proof. View instructions lists each host with its record. Publish the record, then press Check now. Once every host is proved, validation continues on its own, including when you prove the host from another assessment or the project. Nothing is charged while the assessment waits. There is no deadline: the assessment waits until you check again, change the scope with Edit scope, or cancel.

If your organization no longer controls a host, an organization admin can remove its verification. New tests of that host are refused until it is proved again, and monitoring and schedules that reach it pause. Tests that are already running finish.

For wildcard scope, IP addresses or testing on behalf of a client, contact AISafe with the client's written authorization. AISafe reviews the exact hosts and approves them for your organization until the end date of that authorization.

Test users and login instructions

Use Test Users to give the agents accounts to sign in with. Each test user has a name, which is its role in your application (for example admin or member), a username and a password. If the account signs in with a one-time code from an authenticator app, also enter its base32 secret key. Use dedicated test accounts rather than real ones.

Depending on how the account signs in, a test user can also have the URL of its login page, a separate inbox for email verification, or the OAuth token URL, client ID, client secret, scope and audience. The agents receive these with the account. The configuration editor does not display saved secrets again. Finding evidence and PoCs retain values used during testing, including client secrets.

You can add up to ten test users. Several test users can share a role. To test whether one user can read or change another user's data, add two accounts with the same role, for example two member accounts. The agents tell your accounts apart by their usernames.

The agents that explore your application and the agents that test each possible issue all receive your test users. They sign in through your application's own login form, and for an account with a secret key they generate the current six-digit code the way an authenticator app does. They test your application both signed out and signed in.

If your test account must register an authenticator on its first sign-in, AISafe can keep the newly enrolled secret for later sign-ins during that run. It does not replace a secret you supplied or update your saved test-user configuration. Keep the account's current authenticator secret for future runs.

If your application asks a test account to choose a new password the first time it signs in, AISafe chooses a strong password, sets it through your application's own form and uses it for every later sign-in during that run. The assessment's report lists that test user with the new password and marks it as changed by AISafe at the first sign-in. AISafe does not update your saved test-user configuration, so save the new password there before you run another assessment.

Before testing starts, AISafe signs every test user in once. The assessment stops at that point, and its credits are refunded, when you need to change something:

• your application rejects a test user's password. When the application answers a locked account exactly as it answers a wrong password, AISafe cannot tell the two apart, so the message asks you to check both the password and whether the account is locked;
• your application refuses a test user's API key exactly as it refuses a key that does not exist, while it accepts another test user's key. Check the key and the header name saved for that test user;
• your application reports that the account is locked;
• it asks for a code from a second factor the account already has while you saved no secret key for it;
• it shows a CAPTCHA on sign-in;
• it does not answer at all;
• the test user signs in with a link or code sent by email to an inbox AISafe cannot read. Turn the emailed sign-in off for the account, or add a test user that signs in with a password or an API key;
• the test user signs in through a single sign-on provider that AISafe cannot complete, such as Authenticate with Google. Add a test user that signs in to your application directly with a password or an API key, such as a local test account that bypasses single sign-on;
• your application's sign-in sends the test user to another host, such as an identity provider on auth.example.com, that the assessment's scope does not include, so AISafe cannot reach it. Verify a domain that covers that host, or add the host to Additional allowed domains, and run the assessment again.

The assessment stops before it tests anything rather than testing your application as a signed-out visitor. The failed assessment names each such account and says what to check, so you can fix it and reopen the assessment. A setup your application asks for on the first sign-in, such as adding an authenticator or choosing a new password, is AISafe's to handle. If a test user cannot be signed in for any other reason, AISafe treats it as its own problem to repair and the assessment continues.

AISafe reuses the application's observed session cookies, credential headers and browser storage when moving between HTTP tests and browser tests. This also supports applications that use the same token in more than one place. A principal response can return HTTP 200 both signed out and signed in when its JSON contains your supplied username or email only after sign-in. A test user that signs in with an API key or a static bearer token needs only the header name and the key. AISafe counts it as signed in when one request succeeds with the account's key and is refused with 401 or 403 both without a key and with a key that does not exist. The account is whoever that response describes.

For tenant-specific hosts, an account only needs to sign in where it has membership. AISafe records explicit membership refusals separately from failed credentials and requires each account to sign in on at least one target host. Email or SMS-forwarded sign-in codes can be used when they arrive in an inbox configured for the run to read. Codes from another account's inbox are refused.

The agents' instructions never contain a password or a secret key. The agents enter them into your login form or a login request without seeing them, and they are told never to write them down. Findings and reports name an account by its role and username. When a finding's evidence shows a login request, it shows the request exactly as it was sent, password included, so that you can reproduce the finding with the same account. The live Traffic view replaces the password and any six-digit authenticator code with [test user secret].

Use the login instructions to describe anything about signing in that the agents cannot find on their own, such as the address of the login page or an extra step. The instructions apply to every test user. Request tokens such as API keys belong in Custom headers.

Saved passwords and secret keys are not displayed again. If you replace saved test users, enter the credentials for every account you want to keep.

The Try to create new users option, off by default, lets the agents register their own accounts through your application's normal public sign-up when that helps them compare one account or tenant against another. This is useful when you supply one account or none. The agents use only your public sign-up on an authorized target, never an admin or internal user-creation endpoint, and they record each account they create, with its username or email and the host, in the report so you can remove it afterwards.

API description

If your target is an API with an OpenAPI 3 or Swagger 2 document, the agents use the operations it lists, with their path, query, header and cookie parameters and the fields of their request bodies. That includes fields your own client never sends, which the agents test as well.

AISafe looks for a document your application serves at a common location, such as /openapi.json, /openapi.yaml or /swagger.json. If your document is somewhere else, give its URL as api_spec_url when you create a black-box assessment through the API (POST /api/v1/assessments or the draft endpoints). The URL must use the same scheme, host and port as one of your target URLs. AISafe requests it at the start of the run, through the same scope and rate limit as the rest of the test, and reads documents of up to 16 MiB. The dashboard does not show this setting yet.

Custom headers

Optional headers to include in all requests, for example an API key or a session token your application expects. You can add up to twenty, with one entry per header name.

Rate limiting

The requests-per-second cap applies to each allowed origin across HTTP paths within a sandbox. The initial burst equals that rate, so a cap of one allows one immediate request. Reinstalling the sandbox policy does not refill the bucket. WebSocket upgrades and each client frame consume the same allowance; a frame that exceeds the bounded wait queue closes the connection. Use the cap for production or shared staging environments.

Excluded paths

Optional URL paths to skip during testing, up to one hundred. Use this to protect sensitive endpoints, avoid destructive actions, or stay within scope boundaries. A literal /admin excludes that path. A final wildcard, such as /admin/*, excludes that path and all descendants, including /admin/users/delete. An interior wildcard, such as /admin/*/edit, matches one path segment. Exclusions apply to HTTP requests inside HTTPS tunnels too.

Reachability and scope

The agents operate within the scope you define. Target traffic stays within the provided target URLs, any additional allowed domains you configure, and the hosts under any domain your organization verified (Hosts your application calls). AISafe’s callback server is the separate exception described below. This keeps the test focused and stops the agent from testing areas you did not intend to test.

A target URL with a path limits testing to that path and its descendants. For example, https://app.example.com/app allows /app and /app/items/1, while /admin and /application remain outside scope. An additional allowed domain grants all paths on that origin, and a verified domain grants all paths and ports on itself and every host under it, except the host of a target URL with a path, which stays limited to that path. A Rules of Engagement host exclusion such as *.example.com excludes every subdomain at any depth, but does not exclude example.com itself. An optional port suffix limits the exclusion to that port. Exclusions take precedence over allowed targets.

AISafe also allows captured, rate-limited HTTP and HTTPS traffic to its callback server for out-of-band tests. Callback names connect only to addresses resolved from that server when the policy is installed, on ports 80 and 443. Custom target headers are not sent to the callback server. If the callback server cannot be resolved while the policy is installed, target testing continues without callback access and OOB tools tell the agent to continue without OOB. OOB DNS address records must stay on the callback server; aliases to other servers are refused. TXT records remain available for verification tests.

Three limits keep the run safe:

• The sandbox egress is allowlisted. It reaches the hosts you specify, every host under a domain your organization verified (see Hosts your application calls), your test users' OAuth token URLs and the pinned callback server; the platform blocks other hosts.
• The sandbox connects only to public internet addresses. When a host in your scope resolves to a loopback, private, link-local or other internal address (for example 127.0.0.1, 10.0.0.5 or 169.254.169.254), the request is refused and recorded as blocked, even though the host name is in scope. Make sure each target's DNS name resolves to a public address.
• If the agent meets a redirect to a domain outside your scope, it does not follow it. This keeps the test in bounds even when your application links to external services.

Because egress is allowlisted and redirects outside scope are not followed, the target must be reachable directly from the sandbox. Do not expect the agent to follow a chain that leaves your configured domains.

The check before you are charged

When you press Start, AISafe requests each target from our network before it takes any payment. The check takes seconds and runs no analysis. If a target does not answer, the run does not start and no credits leave your balance.

If you set custom headers, the check sends them too. A target that answers 401 or 403 to a request carrying your headers stops the start as well, because otherwise the run would spend its budget on requests that a login page blocks.

The message names the target, says what happened, and says what to check. Common causes:

• A typo in the hostname, or a DNS record that is not public.
• A firewall or IP allowlist that only admits addresses you know about.
• A certificate that has expired or does not cover the hostname.
• A header, cookie or token that has expired since you saved it.

If your target only accepts traffic from known addresses, email [email protected] with your assessment code. We will give you the addresses we test from and set it up with you.

Once you start

Once your test users have signed in, the agents map the target before any deeper testing, signed out and, when you saved test users, signed in. See How it works.

Agents are instructed to run destructive or irreversible tests only on objects and accounts they created for that test. They must never delete, deactivate or demote users, delete or reset data they did not create, or transfer ownership. The instructions also forbid real purchases and emails or messages to addresses the agents do not control. If a test would require such an action on existing data, the agent records the check with the evidence it has. These rules guide the agents' decisions; the network guard does not enforce them. Keep sensitive actions in your excluded paths.

Apart from the authenticator enrollment and password change that the first sign-in may require, agents may read your test users' account settings but must not submit changes to their credentials or sign-in setup. A test that needs a wrong password or a wrong second-factor code uses an account the agents registered themselves. AISafe also blocks such requests itself: a sign-in request that carries a wrong secret for one of your test users is refused before it reaches your application, whether it comes from the browser or from a script. Injection tests on your sign-in form use a disposable identity with a random secret, so they never send one of your test users' usernames with a guessed password. If AISafe blocks a test this way, that check is recorded as inconclusive and the assessment continues. While your application waits for a test user's second-factor code, AISafe lets through only that user's current authenticator code or the codes of the 30-second windows just before and after it.

The sign-in check described in Test users and login instructions runs once, before testing starts. If your application refuses a test user later in the run, for example because its password was changed or the account was locked during the assessment, the assessment continues with the other users and the checks that needed that user are recorded as inconclusive. A rejected password, a locked account or a missing second factor keeps that user out of testing for the rest of the assessment. If the application accepts the sign-in but then treats the user as signed out, AISafe tries again after a short interval, so testing goes on once sign-in works again. When the assessment reports a refusal, check the user's password, second factor and account status. When your target is briefly unavailable, AISafe retries a limited number of times. If the outage lasts longer, the affected check is inconclusive and the test user stays available.

Limits on what you send

Every list on this page has a maximum length, and the entries have to be distinct. If you go over a limit or repeat an entry, AISafe refuses the input with a clear message that names the limit. We never quietly trim a list to fit, because the results would then suggest that we tested something we did not.

These limits apply to what you send us, never to what we return. An assessment reports every finding it produced, however many there are.

For an assessment on behalf of a client, contact AISafe to discuss authorization.