PlexTrac
Application Security- Overview
- Setup
- Data & mappings
- Operations & API
- Changelog
The PlexTrac connector integrates with the PlexTrac penetration-testing and proactive-security platform. It synchronizes the assets, findings, finding definitions, assessments, and client tenants tracked in PlexTrac into Brinqa, allowing pentest results to be unified with the rest of an organization's risk data.
The connector syncs five object types:
- Client — the PlexTrac client/tenant container.
- Assessment — questionnaire-based assessments performed for a client.
- Host — assets (hosts) tracked in PlexTrac, mapped to the Host model.
- Pentest Finding — instances of findings on affected assets, mapped to the Pentest Finding model.
- Pentest Finding Definition — the deduplicated finding definitions (including CVSS scoring) derived from the same finding records, mapped to the Pentest Finding Definition model.
Data retrieved from PlexTrac
| Connector Object | Required | Maps to Data Model |
|---|---|---|
| Client | Yes | Client |
| Assessment | Yes | Assessment |
| Host | Yes | Host |
| Pentest Finding | Yes | Pentest Finding |
| Pentest Finding Definition | Yes | Pentest Finding Definition |
Model relationships
note
For detailed steps on how to view the data retrieved from PlexTrac in the Brinqa Platform, see How to view your data.
Connection settings
When setting up a data integration, select PlexTrac from the Connector dropdown and provide the following:
| Setting | Required | Default | Description |
|---|---|---|---|
| API URL | No | — | API URL |
| Username | No | — | PlexTrac username |
| Password | No | — | PlexTrac password |
| Page size | No | — | Maximum number of records to get per API request |
| Parallel requests | No | — | Maximum number of parallel API requests |
| Custom Properties | No | — | Comma-delimited list of case-insensitive custom property names to be promoted to PentestFinding model |
| Maximum retries | No | — | The maximum number of retry attempts before giving up a request |
Authentication
PlexTrac uses a username/password login that returns a short-lived Bearer token. The connector calls the authenticate endpoint with the configured Username and Password, caches the returned token, and presents it as a Bearer Authorization header on every subsequent API request. The token is treated as valid for 15 minutes (the PlexTrac documented lifetime); the connector re-authenticates automatically when the token is near or past expiry.
Endpoint
| Method | URL |
|---|---|
| POST | /api/v1/authenticate |
Request Headers
| Header | Value |
|---|---|
Content-Type | application/x-www-form-urlencoded |
Request Body
The credentials are sent as URL-encoded form parameters:
username={username}&password={password}
Sample Response
{
"status": "success",
"tenant_id": 0,
"cookie": "",
"token": "eyJhbGciOiJ...redacted...token"
}
Response Fields
| Field | Description |
|---|---|
status | Result of the authentication request (e.g. success). |
tenant_id | Tenant identifier associated with the authenticated user. |
cookie | Session cookie returned by PlexTrac. |
token | Bearer access token used to authorize subsequent API calls. |
Using the Token
Every subsequent request includes the token in the Authorization header:
Authorization: Bearer {token}
The token has no expiry value in the response, so the connector assigns a 15-minute lifetime and refreshes it automatically before it expires.
Sync Behavior
Every sync is a full sync: each run retrieves the complete data set for the object being synced.
The connector accepts a sync token and converts it to a since timestamp, and each model receives that value, but no model currently applies it as a filter — so a token from a previous run does not narrow the next one. Records are emitted as CREATE_OR_UPDATE deltas stamped with the sync start time, not with each record's own modification time. Incremental (delta) filtering is not implemented; see each object's Sync Duration Parameter for what that object does and does not narrow.
Server-side narrowing is available through the per-object Operation Options (severity, status, tags, and similar), and stale records are aged out by the lifecycle strategies documented per object rather than by delta detection.
Pentest Finding and Pentest Finding Definition are built from the same finding records, and within a single sync transaction the first of the two to run caches those records to a local store keyed on TRANSACTION_ID; the second replays them from disk instead of re-fetching every report. That is a within-transaction optimization, not a cross-run delta.
How to obtain PlexTrac credentials
Note: The PlexTrac user must have at least the Analyst or Standard User role assigned to them in order to retrieve data from the PlexTrac API. For additional information on roles and users, see PlexTrac documentation.
Attribute mappings
Expand the sections below to view the mappings between the source and the Brinqa data model attributes:
Client
| Source Field Name | SDM Attribute |
|---|---|
ClientResource.client_id | CLIENT_ID |
ClientResource.cuid | UID |
ClientResource.cuid | NAME |
ClientResource.custom_field | CUSTOM_FIELD |
ClientResource.description | DESCRIPTION |
ClientResource.doc_type | DOC_TYPE |
ClientResource.logo | LOGO |
ClientResource.name | NAME |
ClientResource.poc | POC |
ClientResource.poc_email | |
ClientResource.tags | TAGS |
ClientResource.tenant_id | TENANT_ID |
ClientResource.users (keys) | USERS |
| sync time | LAST_CAPTURED |
Assessment
| Source Field Name | SDM Attribute |
|---|---|
AssessmentResource.all_approved | ALL_APPROVED |
AssessmentResource.assess_id | UID |
AssessmentResource.assess_id | NAME |
AssessmentResource.assessment_date | LAST_ASSESSED |
AssessmentResource.assessment_title | NAME |
AssessmentResource.client_id | TARGETS |
AssessmentResource.client_id | CLIENT_ID |
AssessmentResource.client_name | CLIENT_NAME |
AssessmentResource.doc_type | DOC_TYPE |
AssessmentResource.framework.categories | FRAMEWORK_CATEGORIES |
AssessmentResource.framework.id | FRAMEWORK_ID |
AssessmentResource.framework.label | FRAMEWORK_LABEL |
AssessmentResource.framework.title | FRAMEWORK_TITLE |
AssessmentResource.framework.version | FRAMEWORK_VERSION |
AssessmentResource.has_reviewers | HAS_REVIEWERS |
AssessmentResource.last_updated_by[].email | LAST_UPDATED_BY |
AssessmentResource.questionnaire_id | QUESTIONNAIRE_ID |
AssessmentResource.reviewers[].email | REVIEWERS |
AssessmentResource.saved_at | SAVED_AT |
AssessmentResource.tenant_id | TENANT_ID |
| sync time | LAST_CAPTURED |
Host
| Source Field Name | SDM Attribute |
|---|---|
AssetResource.asset | NAME |
AssetResource.assetCriticality | ASSET_CRITICALITY |
AssetResource.client_id | CLIENT_ID |
AssetResource.createdAt | CREATED_AT |
AssetResource.cuid | CUID |
AssetResource.data_owner | DATA_OWNER |
AssetResource.description | DESCRIPTION |
AssetResource.dns_name | DNS_NAMES |
AssetResource.dns_name (if private) | PRIVATE_DNS_NAMES |
AssetResource.dns_name (if public) | PUBLIC_DNS_NAMES |
AssetResource.host_fqdn | HOST_FQDN |
AssetResource.host_rdns | HOST_RDNS |
AssetResource.hostname | HOSTNAMES |
AssetResource.id | UID |
AssetResource.id | NAME |
AssetResource.knownIps | IP_ADDRESSES |
AssetResource.knownIps (private) | PRIVATE_IP_ADDRESSES |
AssetResource.knownIps (public) | PUBLIC_IP_ADDRESSES |
AssetResource.mac_address (normalized) | MAC_ADDRESSES |
AssetResource.netbios_name | NETBIOS_NAME |
AssetResource.notes | NOTES |
AssetResource.operatingSystems | OPERATING_SYSTEMS |
AssetResource.parent | PARENT |
AssetResource.pci_status | PCI_STATUS |
AssetResource.physical_location | LOCATION |
AssetResource.ports | PORTS |
AssetResource.system_owner | OWNER |
AssetResource.tags | TAGS |
AssetResource.total_cves | TOTAL_CVES |
AssetResource.updatedAt | UPDATED_AT |
constant Host + AssetResource.type | CATEGORIES |
| sync time | LAST_CAPTURED |
Pentest Finding
| Source Field Name | SDM Attribute |
|---|---|
| derived from normalized severity | SEVERITY_SCORE |
FindingResource.affected_assets[].id | TARGETS |
FindingResource.assignedTo | ASSIGNED_TO |
FindingResource.client_id | CLIENT_ID |
FindingResource.client_name | CLIENT_NAME |
FindingResource.closedAt | LAST_FIXED |
FindingResource.code_samples[].code | CODE_SAMPLES |
FindingResource.createdAt | SOURCE_CREATED_DATE |
FindingResource.cuid | UID |
FindingResource.cuid | NAME |
FindingResource.custom_field[] (report custom fields) | CUSTOM_{label} |
FindingResource.doc_type | DOC_TYPE |
FindingResource.doc_version | DOC_VERSION |
FindingResource.finding_id | FINDING_ID |
FindingResource.flaw_id | TYPE |
FindingResource.jiraIssue | JIRA_ISSUE |
FindingResource.last_update | SOURCE_LAST_MODIFIED |
FindingResource.reopenedAt | REOPENED_AT |
FindingResource.report_id | REPORT_ID |
FindingResource.report_name | REPORT_NAME |
FindingResource.reportedAt | FIRST_FOUND |
FindingResource.serviceNowTicket | SERVICENOW_TICKET |
FindingResource.severity | SOURCE_SEVERITY |
FindingResource.severity (normalized) | SEVERITY |
FindingResource.source | SOURCE |
FindingResource.status | PROVIDER_STATUS |
FindingResource.status (normalized) | SOURCE_STATUS |
FindingResource.subStatus | SUB_STATUS |
FindingResource.tags | TAGS |
FindingResource.tenant_id | TENANT_ID |
FindingResource.visibility | VISIBILITY |
| sync time | LAST_CAPTURED |
Pentest Finding Definition
| Source Field Name | SDM Attribute |
|---|---|
| derived from normalized severity | SEVERITY_SCORE |
FindingResource.calculated_severity | CALCULATED_SEVERITY |
FindingResource.common_identifiers.CVE[].name, else rebuilt from id and year | CVE_IDS |
FindingResource.common_identifiers.CWE[].id | CWE_IDS |
FindingResource.description | DESCRIPTION |
FindingResource.flaw_id | UID |
FindingResource.flaw_id | NAME |
FindingResource.recommendations | RECOMMENDATION |
FindingResource.references | REFERENCES |
FindingResource.risk_score.CVSS.vector | CVSS_V3_1_VECTOR |
FindingResource.risk_score.CVSS2.vector | CVSS_V2_VECTOR |
FindingResource.risk_score.CVSS3.vector | CVSS_V3_VECTOR |
FindingResource.sev | SOURCE_SEVERITY_SCORE |
FindingResource.severity | SOURCE_SEVERITY |
FindingResource.severity (normalized) | SEVERITY |
FindingResource.severity_key | SEVERITY_KEY |
FindingResource.title | NAME |
| parsed from CVSS v2 vector | CVSS_V2_AV |
| parsed from CVSS v2 vector | CVSS_V2_AC |
| parsed from CVSS v2 vector | CVSS_V2_AU |
| parsed from CVSS v2 vector | CVSS_V2_CI |
| parsed from CVSS v2 vector | CVSS_V2_II |
| parsed from CVSS v2 vector | CVSS_V2_AI |
| parsed from CVSS v2 vector | CVSS_V2_E |
| parsed from CVSS v2 vector | CVSS_V2_RL |
| parsed from CVSS v2 vector | CVSS_V2_RC |
parsed from CVSS v2 vector, else risk_score.CVSS2.subScore.base | CVSS_V2_BASE_SCORE |
parsed from CVSS v2 vector, else risk_score.CVSS2.subScore.temporal | CVSS_V2_TEMPORAL_SCORE |
| parsed from CVSS v3 vector | CVSS_V3_AV |
| parsed from CVSS v3 vector | CVSS_V3_AC |
| parsed from CVSS v3 vector | CVSS_V3_PR |
| parsed from CVSS v3 vector | CVSS_V3_UI |
| parsed from CVSS v3 vector | CVSS_V3_CI |
| parsed from CVSS v3 vector | CVSS_V3_II |
| parsed from CVSS v3 vector | CVSS_V3_AI |
| parsed from CVSS v3 vector | CVSS_V3_E |
| parsed from CVSS v3 vector | CVSS_V3_RL |
| parsed from CVSS v3 vector | CVSS_V3_RC |
parsed from CVSS v3 vector, else risk_score.CVSS3.subScore.base | CVSS_V3_BASE_SCORE |
parsed from CVSS v3 vector, else risk_score.CVSS3.subScore.temporal | CVSS_V3_TEMPORAL_SCORE |
parsed from CVSS v3.1 vector | CVSS_V3_1_AVAILABILITY_REQUIREMENT |
parsed from CVSS v3.1 vector | CVSS_V3_1_MODIFIED_ATTACK_COMPLEXITY |
parsed from CVSS v3.1 vector | CVSS_V3_1_MODIFIED_ATTACK_VECTOR |
parsed from CVSS v3.1 vector | CVSS_V3_1_MODIFIED_PRIVILEGES_REQUIRED |
parsed from CVSS v3.1 vector | CVSS_V3_1_MODIFIED_USER_INTERACTION |
parsed from CVSS v3.1 vector | CVSS_V3_1_MODIFIED_SCOPE |
parsed from CVSS v3.1 vector | CVSS_V3_1_MODIFIED_CONFIDENTIALITY_IMPACT |
parsed from CVSS v3.1 vector | CVSS_V3_1_MODIFIED_INTEGRITY_IMPACT |
parsed from CVSS v3.1 vector | CVSS_V3_1_MODIFIED_AVAILABILITY_IMPACT |
parsed from CVSS v3.1 vector | CVSS_V3_1_CONFIDENTIALITY_REQUIREMENT |
parsed from CVSS v3.1 vector | CVSS_V3_1_INTEGRITY_REQUIREMENT |
parsed from CVSS v3.1 vector, else risk_score.CVSS3_1.subScore.base | CVSS_V3_1_BASE_SCORE |
parsed from CVSS v3.1 vector, else risk_score.CVSS3_1.subScore.environmental | CVSS_V3_1_ENVIRONMENTAL_SCORE |
parsed from CVSS v3.1 vector, else risk_score.CVSS3_1.subScore.temporal | CVSS_V3_1_TEMPORAL_SCORE |
| same values as CVE_IDS | CVE_RECORDS |
| same values as CWE_IDS | WEAKNESSES |
| sync time | LAST_CAPTURED |
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).
Client
Operation options
| Option | Type | Default | Description |
|---|---|---|---|
tags | Comma-separated tag values; filters clients by tag. | — |
Delta sync
Not supported. The connector performs a full sync of Client on every run and applies no incremental date filter.
API
- Type: REST endpoint · Endpoint:
POST /api/v2/clients
Assessment
Operation options
This object does not support any operation options.
Delta sync
Not supported. The connector performs a full sync of Assessment on every run and applies no incremental date filter.
API
- Type: REST endpoint · Endpoint:
GET /api/v2/tenants/{tenantId}/assessments
Host
Operation options
| Option | Type | Default | Description |
|---|---|---|---|
type | Filters assets by type. | — | |
tags | Comma-separated tag values; filters assets by tag. | — |
Delta sync
Not supported. The connector performs a full sync of Host on every run and applies no incremental date filter.
API
- Type: REST endpoint · Endpoint:
POST /api/v2/tenant/assets
Pentest Finding
Operation options
| Option | Type | Default | Description |
|---|---|---|---|
severity | Filters findings by severity. | — | |
status | Filters findings by status. | — | |
source | Filters findings by source. | — | |
findingTags | Comma-separated tag values; filters findings by tag. | — | |
visibility | Filters findings by visibility. | — |
Delta sync
Not supported. The connector performs a full sync of Pentest Finding on every run and applies no incremental date filter.
API
- Type: REST endpoint · Endpoint:
POST /api/v2/clients/{clientId}/reports/{reportId}/findings
Pentest Finding Definition
Operation options
This object does not support any operation options.
Delta sync
Not supported. The connector performs a full sync of Pentest Finding Definition on every run and applies no incremental date filter.
API
- Type: REST endpoint · Endpoint:
POST /api/v2/clients/{clientId}/reports/{reportId}/findings
Changelog
The PlexTrac connector has undergone the following changes:
| Version | Description | Migration Steps |
|---|---|---|
| 3.0.15 | Improvements - Pentest Finding Definitions now carry CVE_IDS, mapped from the finding's common_identifiers.CVE entries; only the CVE bucket is read, so other identifier types (e.g. BUGTRAQ) are ignored, and definitions with no CVE identifiers simply omit the attribute. Buckets PlexTrac returns with a null value ({"BUGTRAQ": null}), and a null common_identifiers map, are skipped - Pentest Finding Definitions now carry CWE_IDS, mapped from the common_identifiers.CWE bucket as CWE-<id>. PlexTrac sends these entries as a bare numeric id, so that is the source; a name is accepted as a fallback for entries that carry one - The same identifiers are also carried on CVE_RECORDS and WEAKNESSES, which hold the CVE and CWE values as related records rather than as plain strings - Added CVSS_V3_1_ENVIRONMENTAL_SCORE to Pentest Finding Definition, sourced from the v3.1 vector when that vector carries environmental metrics, or from risk_score.CVSS3_1.subScore.environmental when PlexTrac reports one. A vector that tailors nothing scores environmental identically to temporal, so no attribute is emitted in that case. It completes the v3.1 environmental family already on the model (modified metrics and the confidentiality/integrity/availability requirements) - Corrected the README's Sync Behavior documentation, which claimed the connector maintained a sync token between runs and applied it as an incremental timestamp filter. Every sync is in fact a full sync: since is passed to each model but no model applies it, and per-record sync tokens carry the sync start time rather than each record's modification time. The Host, Pentest Finding, and Pentest Finding Definition Sync Duration Parameter sections repeated the same claim and were corrected too. No behaviour change — documentation only - Removed TENANT_ID and CLIENT_ID from the Pentest Finding Definition schema; both were declared but never populated. Definitions are deduplicated by flaw_id across every report of every client, so neither value can be attributed deterministically — that linkage lives on Pentest Finding, which carries the instance-level context Bug Fixes - Pentest Finding Definition CVSS scores were missing entirely for tenants whose findings carry scores alongside an empty, absent or unparseable vector, because scores were only ever derived by parsing that vector. The scores PlexTrac reports under risk_score.<system>.subScore are now used to fill each score the vector does not supply, so affected definitions sync with correct CVSS base, temporal and environmental scores. Precedence is per score rather than per scoring system: where the vector supplies a score it still wins, and a reported score is no longer discarded just because the vector happened to supply a different one | • Pentest Finding Definition: TENANT_ID and CLIENT_ID are no longer declared on this object. Neither was ever populated for it, so no synced values change, but any mapping that references them on Pentest Finding Definition should be removed — Action: remove those two attributes from any Pentest Finding Definition mapping; no purge, reconnect or re-sync is needed |
| 3.0.14 | Bug Fixes - Fixed Pentest Finding (and other object) sync silently swallowing page-fetch failures into a null-records sentinel that later crashed with ExecutionException: NullPointerException; a page failure now surfaces as a ConnectorException naming the failing endpoint and cause instead of failing loudly on an unrelated NPE or, worse, ending the sync early with partial/zero results reported as success | N/A |
| 3.0.13 | Bug Fixes - Fixed MismatchedInputException during assessment ingestion caused by polymorphic reviewers and last_updated_by fields returned by the PlexTrac API. Introduced a custom ReviewerListDeserializer to handle array, object, number, string, and null formats gracefully - Fixed host parent asset sync failure by adding @JsonProperty("parentName") mapping to AssetResource.parent() - Fixed @JsonProperty("user_id") mapping on Reviewer.userId() for correct snake_case deserialization - Fixed Reviewer.email() to return Optional<String> — numeric userId values are no longer incorrectly stored as email - Fixed CUSTOM_FIELD schema in Client model — removed incorrect setMultiValued(true) and COLLECTION_CRITERIA mapping (attribute is single-valued, joined with ;) Improvements - Added MockWebServer integration tests ( PlexTracConnectorIntegrationTests) validating connection, client sync, assessment sync (all polymorphic formats), and host sync with parentName mapping - Added LAST_CAPTURED attribute to Assessment, Client, Pentest Finding, and Pentest Finding Definition models - Centralized TENANT_ID and CLIENT_ID attribute management in PlexTracModel via addCommonAttributes() helper; all models use ModelUtil.getCustomAttributeInfos() for schema discovery - Migrated custom AttributeInfo declarations from new AttributeInfoBuilder(...) to AttributeInfos.newAttribute(...) across all model classes - Migrated objectClassInfoTypes() from new HashSet<>() to CollectionUtil.newSet() - Bumped connectors-model version from 1.5.8 to 1.6.19 - Removed STATUS and STATUS_CATEGORY attributes from Pentest Finding model (not required) - Moved API endpoint strings to constants in PlexTracModel (CLIENTS_ENDPOINT, ASSETS_ENDPOINT, REPORTS_ENDPOINT) - Added configurable maxRetries property to PlexTracConfiguration (default 5); replaced hardcoded retry values with BaseModel.INTERVAL_MILLIS and BaseModel.MULTIPLIER constants - Applied Spotless code formatting across all source files | N/A |
| 3.0.12 | New Features - Pentest Findings now include normalized Severity, Source Severity, and Severity Score values, bringing finding severity in line with how severity is reported across other connectors. | N/A |
| 3.0.11 | New Features - Added a Finding ID attribute to Pentest Findings, exposing the PlexTrac finding identifier directly on the finding record. | N/A |
| 3.0.10 | New Features - Added a Custom Properties configuration option. You can now provide a comma-delimited, case-insensitive list of PlexTrac custom property names to promote onto Pentest Finding records, with each named property surfaced as its own dedicated attribute. Improvements - Custom field data on Pentest Findings is now stored under per-property attributes rather than a single combined Custom Field attribute, making individual custom values easier to map and report on. | • Pentest Finding: Custom field data is now stored under individual per-property attributes instead of the single combined Custom Field attribute. Re-sync the PlexTrac connector so finding custom properties are re-populated under the new attributes. |
| 3.0.9 | New Features - Added a Custom Field attribute to Pentest Findings, capturing custom field values defined in PlexTrac. | N/A |
| 3.0.8 | Bug Fixes - Findings with a malformed CVSS v2 vector no longer interrupt synchronization. Invalid vectors are now skipped and logged, allowing the remaining findings to sync successfully. | N/A |
| 3.0.7 | Bug Fixes - Findings with a malformed CVSS v3 or v3.1 vector no longer interrupt synchronization. Invalid vectors are now skipped and logged, allowing the remaining findings to sync successfully. | N/A |
| 3.0.6 | Improvements - Host PCI status is now captured as a text value, ensuring non-numeric PCI status values from PlexTrac are preserved as reported. | • Host: The PCI Status attribute changed from a numeric value to a text value. Re-sync the PlexTrac connector so Host PCI Status values are re-stored in the new format. |
| 3.0.5 | New Features - Added automatic lifecycle management for Hosts. Hosts that have not been seen in a sync for 180 days are now automatically retired. - Pentest Findings now follow the lifecycle of their associated Host, so findings are retired in step with the asset they affect. - Added a Provider Status attribute to Pentest Findings, preserving the original status value as reported by PlexTrac. Improvements - Pentest Finding source status now stores the normalized status value, providing consistent status reporting across findings. | • Pentest Finding: The source status value is now normalized before being stored. Re-sync the PlexTrac connector so existing findings reflect the updated status values. |
| 3.0.4 | Improvements - Improved sync reliability by removing unused response fields that could cause data parsing errors during synchronization. | N/A |
| 3.0.3 | Bug Fixes - Code samples on Pentest Findings are now captured as the actual code content rather than raw object data, so code sample values appear correctly. - Hardened synchronization against empty records returned by the API to prevent intermittent sync errors. | N/A |
| 3.0.2 | Improvements - Improved sync reliability by removing an unused response field that could cause data parsing errors during synchronization. | N/A |
| 3.0.1 | Improvements - Internal reliability improvements to model registration. No change to synced data. | N/A |
| 3.0.0 | Overview The PlexTrac connector integrates with PlexTrac to synchronize penetration testing assets, clients, assessments, and pentest findings into Brinqa. Category: Application Security Models | N/A |