
Validation Agent
Security Testing- Overview
- Setup
- Data & mappings
- Operations & API
- Changelog
The Validation Agent connector integrates with the Brinqa Validation Agent API and synchronizes validation runs — the record of an agent attempting to independently reproduce or disprove a finding on a target asset. Each record carries the run's status, its verdict (for example exploitable, remediated, inconclusive), the rationale behind that verdict, the finding and asset it was run against, the timing of the run, and — when a run does not finish — why it failed.
The connector syncs a single model, Validation, onto the Validation UDM. The endpoint returns the full run history, so a finding that has been validated more than once contributes one record per run, each keyed by its own validation id.
Data retrieved from Validation Agent
| Connector Object | Required | Maps to Data Model |
|---|---|---|
| Validation | Yes | Validation |
Model relationships
For detailed steps on how to view the data retrieved from Validation Agent in the Brinqa Platform, see How to view your data.
A create starts a real validation run and spends the tenant's quota. It is not idempotent, so the connector sends it exactly once and never retries it, unlike the sync's reads.
The one exception is a 401, which the API returns before processing the request: the create is sent again once, with a renewed access token.
Connection settings
When setting up a data integration, select Validation Agent from the Connector dropdown and provide the following:
| Setting | Required | Default | Description |
|---|---|---|---|
| API URL | Yes | https://<your-instance> | Validation Agent base URL |
| Token URL | No | — | OAuth2 token endpoint that exchanges the client credentials for an access token. Leave the three credential fields empty to call an unauthenticated server |
| Client ID | No | — | OAuth2 client ID of the service account |
| Client secret | No | — | OAuth2 client secret of the service account |
| Maximum retries | No | 5 | Maximum number of retry attempts before giving up a request |
Authentication
Method: OAuth 2.0 client credentials
The connector exchanges a client ID and secret for a short-lived access token, then sends that token on every API request. The tenant is carried in the token, so no tenant is configured.
Endpoint
| Method | URL | Used by |
|---|---|---|
POST | {tokenUrl} | Token exchange |
GET | {baseUrl}/api/v1/me | Connection test |
GET | {baseUrl}/api/v1/validations | Sync |
POST | {baseUrl}/api/v1/validations | Create |
Request Headers
| Header | Value |
|---|---|
Content-Type | application/x-www-form-urlencoded |
Request Body
grant_type=client_credentials&client_id=<clientId>&client_secret=<clientSecret>
Sample Response
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 300,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "profile email"
}
Response Fields
| Field | Type | Description |
|---|---|---|
access_token | String | Bearer token sent on every API request |
expires_in | Integer | Token lifetime in seconds |
refresh_expires_in | Integer | Refresh token lifetime; 0, as no refresh token is issued |
token_type | String | Always Bearer |
not-before-policy | Integer | Identity provider revocation policy; not used |
scope | String | Scopes granted to the client; not used |
Usage
Every API request carries the token, together with the JSON headers:
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json
The token is reused until a minute before it expires, or for half its lifetime when that is longer (a token valid for 90s is renewed after 45s), then requested again with the same credentials. A token response with no positive expires_in is treated as valid for 300s. A 401 from the API renews the token and repeats the request once, which covers a token revoked before its expiry; a second 401 fails the operation with an error asking to check the client ID and secret and that the tenant is onboarded. The API answers an expired token and a tenant mismatch with the same 401, so the error cannot tell them apart.
Leave tokenUrl, clientId and clientSecret all empty to call an unauthenticated server, such as a mock; the connector then sends no Authorization header. Setting only some of them fails validation.
How to obtain Validation Agent credentials
Obtain the required credentials (url) from your Validation Agent administrator or the Validation Agent admin console, then enter them in the connection settings above.
The API does not define an error payload yet, so the connector surfaces the body of a non-2xx response verbatim as the error message rather than parsing it into an assumed envelope.
A failed token request reports only its HTTP status, never the response body, since an identity provider may echo the client back. The token exchange is never logged.
A 400, 401 or 403 from the token endpoint is reported as a credential problem and any other 4xx as a wrong token URL; neither is retried. A 408, 429 or 5xx is temporary and retried up to maxRetries.
Attribute mappings
Expand the sections below to view the mappings between the source and the Brinqa data model attributes:
Validation
| Source Field Name | SDM Attribute |
|---|---|
| Sync time | LAST_CAPTURED |
ValidationResource.agent_id | AGENT_ID |
ValidationResource.asset_display_name | VALIDATED_ASSET_NAME |
ValidationResource.completed_at | DATE_COMPLETED |
ValidationResource.created_at | SOURCE_CREATED_DATE |
ValidationResource.elapsed_seconds | ELAPSED_SECONDS |
ValidationResource.external_finding_id | EXTERNAL_FINDING_ID |
ValidationResource.external_finding_id | FINDING |
ValidationResource.failure.code | FAILURE_CODE |
ValidationResource.failure.message | FAILURE_MESSAGE |
ValidationResource.finding_display_name | VALIDATED_FINDING_NAME |
ValidationResource.finding_id | FINDING_ID |
ValidationResource.id | UID |
ValidationResource.id | NAME |
ValidationResource.id | VALIDATION_ID |
ValidationResource.proof_lanes | PROOF_LANES |
ValidationResource.rationale | RATIONALE |
ValidationResource.remediation_available | REMEDIATION_AVAILABLE |
ValidationResource.session_id | SESSION_ID |
ValidationResource.source | FINDING_SOURCE |
ValidationResource.status | STATUS |
ValidationResource.summary | SUMMARY |
ValidationResource.updated_at | SOURCE_LAST_MODIFIED |
ValidationResource.verdict | VERDICT |
Operations & API
Expand each connector object to see its operation options, delta-sync behavior, and the API it uses. See connector operation options for how to apply operation options (keys and values are case-sensitive).
Validation
Operation options
This object does not support any operation options.
Delta sync
Supported. The connector performs an incremental (delta) sync via the since sync token, filtering on updated_at.
API
- Type: REST endpoint · Endpoint:
GET /api/v1/validations - Default filters: None —
updated_at_fromis sent only on an incremental sync;updated_at_tois not used
- The connector sends no
limit, so it relies on the API returning the complete window. The envelope exposes no cursor, so if the API applies a server-side default limit instead, a sync would truncate silently. - The payload carries a
targetkey that is null on every record observed so far. Its shape is unknown, so it is deliberately not deserialized; unknown keys are ignored rather than guessed at. EXTERNAL_FINDING_IDandFINDINGcarry the sameexternal_finding_idon purpose: the first keeps the raw value as the API returned it, the second resolves it against the Brinqa finding'suidto link the validation, and stays empty when nothing matches.- Records with no
sourcecannot be classified as Brinqa's or PlexTrac's. They are skipped like PlexTrac's; both counts are logged as warnings. tenant_idis returned by the API but is platform-internal; it is deserialized and deliberately not mapped onto the model.target_asset_idandasset_idare the Validation Agent's own asset uuids and resolve against no Brinqa asset, so they are deserialized and deliberately not mapped; the model carries noTARGETSorRUNS_ON.- The UDM declares an
approvalModeattribute that the API does not currently expose, so it is left unmapped.
Changelog
The Validation Agent connector has undergone the following changes:
| Version | Description | Migration Steps |
|---|---|---|
| 3.0.0 | Overview The Validation Agent connector integrates with the Brinqa Validation Agent to synchronize validation runs — the record of an agent independently reproducing or disproving a finding on a target asset, with its verdict and supporting rationale. It can also start a validation run for a finding against a target address; the result of that run arrives through the regular sync. Only validations requested from Brinqa are synchronized. The assets a run targeted and ran on are not linked: the API identifies them by the Validation Agent's own asset ids, which match no Brinqa asset. The connector authenticates with an OAuth2 client ID and secret issued for the tenant; leaving all three authentication settings empty connects to an unauthenticated server, such as a mock. Category: Security Testing Models | N/A |