Reports are the middle-level objects housed under a client and contain report details. The Report object does not hold a list of findings, but each finding includes the ID of a report.
The following table explains the fields and data types stored for a report. Fields are presented in alphabetical order by object field name.
name
name of affected assets
dict {str, {AFFECTED ASSET Object}
status
status of report
string ["Draft", "Ready For Review", "In Review", "Approved", "Published"]
includeEvidence
identifies if the report includes evidence
Boolean
report_id
the UUID of the report
integer
client_id
client that the report belongs to
integer
doc_type
field in database to identify object
"report": DB type identifier
reportType
type of report
"default"
tags
any tags associated with the report
string array
custom_field
custom field(s) added to a report
array[ { "label": str, "value": str } ]
custom_fields
container for fields used to track information about the report executive summary narratives; id (narrative UUID), label (title of narrative), tags (any tags applied to narrative), text (narrative content), isFromNarrativesDB (null/true value identifying if the content is from NarrativesDB).
array[ { "id": str, "label": str, "tags": array[str], "text": str, "isFromNarrativesDB": null or true
template
if the report did not use the default template, the custom report UUID is listed
string || null: UUID of report template
start_date
date report was started
null: Zulu date time format
end_date
date report was closed
null: Zulu date time format
fields_template
if the report did not use the default fields template, the custom fields template UUID is listed
string || null: UUID of fields/finding template
exec_summary
a container field that contains any custom fields created for the report
{ "custom_fields": array[ { "id": str: CUID of report narrative, "label": str, "tags": array[str], "text": str, } ] }
isTrackChanges
defines if the rich-text field track changes feature is turned on at the report level (a value of "true" means it is turned on, while a value of "false" means it is turned off and track changes is done per rich-text field)
null or true
The report object stored in the database is a nested JSON object. Below is a screenshot and sample downloadable file that displays the structure of database objects.
PlexTrac data is categorized into clients, reports, findings, and assets, which are the primary containers holding information stored in Plextrac. The Clients module holds assets and reports, while reports hold findings.
While these objects exist as their type in the database, some fields about an object are stored both on the object and as values inside other objects. The most common example of this is affected assets and vulnerabilities.
Here is a list of object structures that have been defined:
Findings are the most common object in PlexTrac and contain data detailing an exploit.
Findings also exist in client asset information in the form of an affected asset and contain the relationship information about which client assets are affected, which is tracked in the affected_assets field.
For each client asset, the finding affects, an object exists in that field's list containing information and metadata about the client asset and how it relates to the finding. Since the objects stored in affected_assets contain this extra relationship metadata, these items are considered separate objects called affected asset objects.
The following table explains the fields and data types stored for a finding. Fields are presented in alphabetical order by object field name.
The required fields when creating a finding are title, severity, and description.
affected_assets
name of affected assets
dict {str, {AFFECTED ASSET Object}
assignedTo
email address of user that finding is assigned to
string
client_id
client that the finding belongs to
integer
closedAt
when finding was closed
integer in epoch milliseconds, such as "1662588579026"
common_identifiers
includes CVE scores, CWE scores, and code that is related to the finding (added in the Code Sample tab when editing a finding)
"CVE": [{ "name": str, "year": int, "id": int, "link": str } ], "CWE": [ { "name": str, "id": int, "link": str } ] }, "code_samples": [ { "caption": str, "code": str, "id": str } ] }
createdAt
when finding was created in
integer in epoch milliseconds, such as "1662588579026"
description
description of finding
string
doc_type
field in database to identify object
string
doc_version
version of PlexTrac when finding was created. Should not be added to create or update requests
string
exhibits
an image or video related to the finding (added in the Screenshots/Video tab when editing a finding)
array: {"assets": [ { "asset": str, "id": str } ], "caption": str, "exhibitID": str:, "index": int, "type": str: MIME type image, such as .png}
fields
includes any added custom fields, plus any CVSS 3.0 score, CVSS 2.0 score, and 'general' score values entered for a finding
dict {str, dict {label: str, value: str}, "scores": { "cvss", { "type": "cvss", "value": str, "label": str, "calculation": str }, "cvss3", { "type": "cvss3", "value": str, "label": str, "calculation": str }, "general", { "type": "general", "value": str, "label": str, "calculation": str } } },
flaw_id
the unique identifier of a finding and is generated based on the finding title, but since a finding with the same title can exist in different reports, this means flaw_id is not unique across the platform
integer
last_update
when finding was last modified
integer in epoch milliseconds, such as "1662588579026"
repoenedAt
when finding was reopened
integer in epoch milliseconds, such as "1662588579026
report_id
ID of report finding is associated with
integer
report_name
name of report
string
risk_score
the total risk score of the finding for CVSS v3.1, CVSS v3.0, CVSS v2.0, and CWSS
"CVSS3": "overall": int, "vector": str, "subScore": "base": int
selectedScore
the identified selected score for the finding
string
severity
severity of finding
string
slaData
SLA status of finding
{"title": str, "timeToExpire": str }
source
source of finding
string
status
status of finding
string
subStatus
substatus of finding
string
tags
any tags associated with finding
string array
title
title of finding
string
visibility
visibility of finding
string
The finding object stored in the database is a nested JSON object. Below are screenshots and a sample downloadable file that displays the structure of different database objects.
continued
Assets are stored at the client level, and only the single doc_type value of "client_asset" exists in the database. An asset can exist as a standalone file added for a client through the Clients module or associated with a finding referred to as an affected asset.
An affected asset refers to a client_asset object with extra properties stored on the finding object. Although it doesn't have its own type or location in the database, it can still be considered a real object since it is technically distinct and exists within the finding object.
The following table explains the fields and data types stored for an asset. Fields are presented in alphabetical order by object field name.
The only required field when creating an asset is the asset name.
asset
name of asset
string
assetCriticality
value capturing the asset criticality that must be one of five provided values
string from list: "Critical", "High", "Medium", "Low", "Information"
assignedTo
email of user vulnerability is assigned to
string
child_assets
assets identified as belonging to this asset
dict {asset str: UUID of asset, dict {CHILD ASSET Object}
client_id
client that the asset belongs to
integer
closedAt
time vulnerability was closed
integer in epoch milliseconds, such as "1661376746781"
created
when asset was created
string: Zulu date time format, such as "2022-05-20T20:43:59.405Z"
createdAt
when asset was created
integer in epoch milliseconds, such as "1661376746781"
data_owner
name of owner
string (defaults to "Data Owner")
description
description of asset
string
dns_name
name of dns
string (defaults to "DNS Name")
doc_type
field in database to identify object
string
evidence
evidence ID of vulnerability
array string UUID
findings
list of findings that the asset is associated with and is autogenerated to record the relationship between the finding and asset
dict {int: id of finding: dict {VULNERABILITY Object}
host_fqdn
fully qualified domain name of host
string
host_rdns
reverse Domain Name System of host
string, such as "216.58.211.142"
hostname
hostname
string
instances
instances of vulnerability
string: report id value: "report_id": int, "report_severity": str: ["Critical", "High", "Medium", "Low", "Information"], "report_status": str: ["Open", "In Process", "Closed"], "report_flaw_title": str, "createdAt": int: epoch milliseconds, "updatedAt": int: epoch milliseconds
id
asset unique identifier
string: UUID
knownIps
string array
locationUrl
url of related vulnerability
string
mac_address
media access control address unique identifier
string
netbios_name
16-byte name for a networking service or function on a machine running Microsoft Windows Server
string
notes
any added notes to asset
string
operating_system
operating system related to asset
string array
parent_asset
asset ID of parent asset
dict {ASSET Object}
pci_status
PCI compliance status
string: "pass" or "fail"
physical_location
physical location of asset
string
ports
known ports
dict { str: value of number: { "number": str, "service": str, "protocol": str, "version": str }
reopenedAt
when vulnerability was reopened
integer (defaults to "null")
report_id
ID of report that vulnerability is associated with
integer
severity
severity of vulnerability that must be one of five provided values
string from list: "Critical", "High", "Medium", "Low", "Information"
status
status of vulnerability
string: "Open", "In Process", "Closed"
subStatus
substatus of vulnerability
string
system_owner
owner of system
string (defaults to "System Owner")
tags
any tags associated with an asset
string array
title
title of vulnerability
string
total_cves
total CVEs score
integer
type
asset type that must be a specific value
string: "Server", "Workstation", "Network Device", "Application", "General"
updatedAt
date and time when asset was updated
integer in epoch milliseconds
vulnerableParameters
parameters of vulnerability
list {"id": str, "text": str}
Client assets are lower-level objects containing information about an asset or application. They contain some finding information in the form of a vulnerability[link].
Client assets contain the data related to the specific physical machine or web application represented and relational information about which findings they are affected by.
Every client asset object has the findings field. For each finding affecting the client asset, an object in that field's list contains information about the finding in a specific report and additional metadata showing how the client asset relates to the finding.
Objects stored in findings contain additional relational metadata for vulnerability objects.
The child asset contains a subset of the related client asset's information.
Affected assets are not objects with their own database type but a value stored in the affected_assets field of a finding object. It contains information about a client asset being affected and relational metadata about the finding and client asset.
An affected asset object on a finding will have a subset of fields compared to the client asset with the same ID. Some additional fields exist that only make sense when the finding and client asset are viewed together, such as the date the finding started affecting the client asset, the affected ports, location access to vulnerability, vulnerable parameters, and evidence of the affection.
Affected assets are very similar to Vulnerabilities, but the rules and validations defining them differ.
Client objects contain the client's details and are one of the highest-level objects in the database, as all other objects are within the context of a specific client.
The client object does not hold a list of assets or reports; instead, each asset and report contains the ID of a client.
Clients hold a list of client assets representing a physical asset or web application. This list is dynamically populated as files with assets imported via a scan or manually added within PlexTrac.
The following table explains the fields and data types stored for a client. Fields are presented in alphabetical order by object field name.
The name field is the only required field when creating a client.
client_id
UUID of client
integer
classificationId
CUID of the Classification Level for an authorized user for each client
string or null
custom_field
custom fields related to client
array[ { "label": str, "value": str } ]
custom_field/label
label of the custom field
string
custom_field/value
plain text value of the custom field
string
description
description of client
string
doc_type
field in database to identify object
"client": DB type identifier
name
name of Client
string
poc
point of contact for client
string
poc_email
email address of point of contact
string
role
type of role of user associated with a client; will be one of three values to represent roles of Administrator, Standard User, and Analyst
string containing one of the following values: ["ADMIN", "STD_USER", "ANALYST"]
tenant_id
UUID of tenant
integer
users
list of users and roles within a client
dict { str: user email: Dict{ "classificationId": str || null: CUID, "role": str: ["ADMIN", "STD_USER", "ANALYST"] } }
tags
any tags associated with a client
string array
The client object stored in the database is a nested JSON object. Below is a screenshot and sample downloadable file that displays the structure of database objects.
Evidence is a small object attached to affected assets or vulnerabilities. Evidence can be added in the UI by importing scanner outputs or manually through API endpoints to an affected asset on new or existing findings.
The following table explains the fields and data types stored for evidence. Fields are presented in alphabetical order by object field name.
caption
evidence caption
string
code
evidence code
string
id
unique identifier
string: UUID
