https://{region}.api.plerion.com
servers:
- url: https://{region}.api.plerion.com
description: Production API server - Select your preferred region
variables:
region:
default: au
enum:
- au
- sg1
- in1
- us1
security: []
tags:
- name: QUICK_START
x-displayName: Quick Start
description: >-
This section describes how to quickly get started with the Plerion API
using curl. For a more detailed guide, see the sections below.
1. Install curl if it isn't already installed on your machine. To check if
curl is installed, execute curl --version in the command
line. If the output is information about the version of curl, it is
installed. If you get a message similar to command not found:
curl, you need to download and install curl. For more
information, see the curl project
download page.
2. Create a Tenant API key accessing Tenant API Keys Dashboard. Warning: Treat your API key like a password. Do not store it as plain text or expose it in any code base.
3. Use the curl command to make your request. Pass your API
key in an Authorization header. Replace {PLERION_API_KEY}
with your API key.
export PLERION_API_URL=au.api.plerion.com
export PLERION_API_KEY={PLERION_API_KEY}
curl --request GET \\
--url "https://$PLERION_API_URL/v1/tenant/findings" \\
--header "Authorization: Bearer $PLERION_API_KEY"
- name: Overview
x-displayName: Overview
description: >-
Plerion API uses API keys to authenticate requests. You can view and
manage your API keys in the Plerion app Tenant API Keys Dashboard.
API responses are JSON-encoded.
To authenticate to Plerion API send the API Key using bearer auth in the Authorization header
Authorization: Bearer $PLERION_API_KEY
All API requests must be made over HTTPS. Calls made over plain HTTP will
fail. API requests without authentication will also fail.
Plerion uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error with Plerion's servers. Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported. Detailed description for the status code can be found in th Response Status Codes section.
| Status Code | Definition | Description |
|---|---|---|
| 200 | OK | The request has succeeded. |
| 201 | Created | The request has been fulfilled and resulted in a new resource being created. |
| 204 | No Content | The server has fulfilled the request but does not need to return an entity-body. |
| 400 | Bad Request | The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications. |
| 401 | Unauthorized | The request requires user authentication. If the request already included Authorization credentials, then the 401 response indicates that authorization has been refused for those credentials. |
| 403 | Forbidden | The server understood the request, but is refusing to fulfill it. Authorization will not fix the issue and the request SHOULD NOT be repeated. |
| 404 | Not Found | The server has not found anything matching the Request-URI. |
| 405 | Method Not Allowed | The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. |
| 409 | Conflict | The request could not be completed due to a conflict with the current state of the resource. |
| 429 | Too Many Requests | Too many requests occurred during the allotted time period and rate limiting was applied. |
| 500 | Internal Server Error | The request did not complete due to an internal error on the server side. The server encountered an unexpected condition which prevented it from fulfilling the request. |
| 503 | Service Unavailable | The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. |
588158338731au.api.plerion.comcurl command.
export PLERION_API_URL=au.api.plerion.com
export PLERION_API_KEY={$PLERION_API_KEY}
export PLERION_AWS_ACCOUNT_ID=588158338731
# Fetch the template URL
export TEMPLATE_URL=$(curl -s GET "https://$PLERION_API_URL/v1/tenant/cloudformation-templates?type=AWSAccount" -H "Authorization: Bearer $PLERION_API_KEY" | jq -r '.data.templateURL')
# Generate the temporary auth token
export TEMP_AUTH_TOKEN=$(curl -s -X POST "https://$PLERION_API_URL/v1/tenant/integrations/token" -H "Authorization: Bearer $PLERION_API_KEY" | jq -r '.data.token')
# Fetch the external ID
export EXTERNAL_ID=$(curl -s -X GET "https://$PLERION_API_URL/v1/tenant/external-id" -H "Authorization: Bearer $PLERION_API_KEY" | jq -r '.data.externalId')
# Create the stack
export PLERION_STACK_NAME=plerion-aws-integration
aws cloudformation create-stack --stack-name $PLERION_STACK_NAME --template-url $TEMPLATE_URL --capabilities CAPABILITY_NAMED_IAM \
--parameters ParameterKey=ExternalId,ParameterValue=$EXTERNAL_ID \
ParameterKey=PlerionAccountId,ParameterValue=$PLERION_AWS_ACCOUNT_ID \
ParameterKey=AuthToken,ParameterValue=$TEMP_AUTH_TOKEN \
ParameterKey=Capabilities,ParameterValue=ALL \
ParameterKey=KMSKeyAccessMode,ParameterValue="ALL_KEYS" \
ParameterKey=PlerionURL,ParameterValue=$PLERION_API_URL
# Wait for the stack to complete
aws cloudformation wait stack-create-complete --stack-name $PLERION_STACK_NAME
export PLERION_API_URL=au.api.plerion.com
export PLERION_API_KEY={$PLERION_API_KEY}
export PLERION_AWS_ACCOUNT_ID=588158338731
# Fetch the template URL
export TEMPLATE_URL=$(curl -s GET "https://$PLERION_API_URL/v1/tenant/cloudformation-templates?type=AWSAccount" -H "Authorization: Bearer $PLERION_API_KEY" | jq -r '.data.templateURL')
# Generate the temporary auth token
export TEMP_AUTH_TOKEN=$(curl -s -X POST "https://$PLERION_API_URL/v1/tenant/integrations/token" -H "Authorization: Bearer $PLERION_API_KEY" | jq -r '.data.token')
# Fetch the external ID
export EXTERNAL_ID=$(curl -s -X GET "https://$PLERION_API_URL/v1/tenant/external-id" -H "Authorization: Bearer $PLERION_API_KEY" | jq -r '.data.externalId')
# Update an existing stack
export PLERION_STACK_NAME=plerion-aws-integration
aws cloudformation update-stack --stack-name $PLERION_STACK_NAME --template-url $TEMPLATE_URL --capabilities CAPABILITY_NAMED_IAM \
--parameters ParameterKey=ExternalId,ParameterValue=$EXTERNAL_ID \
ParameterKey=PlerionAccountId,ParameterValue=$PLERION_AWS_ACCOUNT_ID \
ParameterKey=AuthToken,ParameterValue=$TEMP_AUTH_TOKEN \
ParameterKey=Capabilities,ParameterValue=ALL \
ParameterKey=KMSKeyAccessMode,ParameterValue="ALL_KEYS" \
ParameterKey=PlerionURL,ParameterValue=$PLERION_API_URL
# Wait for the stack to complete
aws cloudformation wait stack-update-complete --stack-name $PLERION_STACK_NAME
- name: Compliance frameworks
x-displayName: Compliance Frameworks
description: >-
Compliance Frameworks help our customers meet their regulatory and
compliance obligations, and reduce compliance risk, enabling them to
achieve their strategic objectives.
Plerion offers customers hundreds of prebuilt detections delivering
continuous assurance against industry standards and best practices.
- name: Well-Architected frameworks
x-displayName: Well-Architected Frameworks
description: >-
The AWS Well-Architected Framework helps customers design secure,
high-performing, resilient, and efficient cloud infrastructure. Plerion
continuously assesses your environment against the AWS Well-Architected
pillars, aligning your architecture with AWS best practices and
accelerating improvement.
- name: Tenant usage
x-displayName: Tenant Usage
description: Plerion Usage information for the Tenant
- name: Audit logs
x-displayName: Audit Logs
description: >-
Audit logs provide a comprehensive trail of user activities and system
operations within a tenant.
These logs capture important events such as user logins, API calls,
configuration changes, and other security-relevant activities. Audit logs
help with compliance, security monitoring, and troubleshooting.
paths:
/v1/tenant/vulnerabilities:
get:
tags:
- Vulnerabilities
summary: List
description: >-
Use the list vulnerabilities API to filter vulnerabilities across the
tenant with many options
from Organization, Tenant, Integration, Asset, Severity, etc. By default
all vulnerabilities
are returned.
Date range filtering is supported using the `firstObservedAtStart` and
`firstObservedAtEnd` parameters:
- `firstObservedAtStart` alone: Includes vulnerabilities observed from
the specified date to the present.
- `firstObservedAtEnd` alone: Includes vulnerabilities observed up to
the specified date.
- Both provided: Includes vulnerabilities observed within the specified
date range.
Date strings must follow ISO 8601 format (e.g., `2023-02-01T18:09:07Z`).
operationId: listTenantVulnerabilities
parameters:
- $ref: '#/components/parameters/paramAuthHeader'
- in: header
name: Content-Type
description: application/json
schema:
type: string
- in: query
name: vulnerabilityIds
description: >-
Filter vulnerabilities on vulnerability ids. Accepts a
comma-separated list with a maximum length of 100
schema:
type: string
example: CVE-2022-22965,CVE-2022-22966,CVE-2022-22967
- in: query
name: assetIds
description: >-
Filter vulnerabilities on asset ids. Accepts a comma-separated list
with a maximum length of 10
schema:
type: string
example:
- prn:assets:a,prn:assets:b
- in: query
name: providers
description: >-
Filter vulnerabilities based on provider. Accepts a comma-separated
list of providers.
schema:
type: string
enum:
- AWS
- Azure
- GCP
- Kubernetes
example: AWS,GCP
- in: query
name: executionIds
description: >-
Filter vulnerabilities on execution ids. Accepts a comma-separated
list with a maximum length of 10
schema:
type: string
example: 1678607803935,1778607801234
- in: query
name: integrationIds
description: >-
Filter vulnerabilities on integration ids. Accepts a comma-separated
list with a maximum length of 10
schema:
type: string
example: UUID1,UUID2
- in: query
name: assetGroupIds
description: >-
Filter vulnerabilities on asset group ids. Accepts a comma-separated
list of asset group ids.
schema:
type: string
example: UUID1,UUID2
- in: query
name: environmentIds
description: >-
Filter vulnerabilities on the environment. This parameter accepts
any combination of environment name or environment IDs (UUIDs) in a
comma-separated list.
**Supported environment names:**
- `production` - Production environment
- `non-production` - Non-production environment
schema:
type: string
example: production,550e8400-e29b-41d4-a716-446655440000
- in: query
name: packageName
description: Filter vulnerabilities on a package name.
schema:
type: string
example: lodash
- in: query
name: regions
description: Filter vulnerabilities on asset regions.
schema:
type: string
example: us-east-1,us-west-2
- in: query
name: targetName
description: >-
Filter vulnerabilities on a target name. For ECS Task Definitions
this will be `{TaskDefinition}:{revision} > {containerImage}`
schema:
type: string
example: EcsTaskDefinition:15 > nginx:1.19.1-alpine-perl
- in: query
name: targetType
description: Filter vulnerabilities on a target type.
schema:
type: string
example: targetType
- in: query
name: targetClass
description: Filter vulnerabilities on a target class.
schema:
type: string
example: lang-pkgs,os-pkgs
- in: query
name: hasKev
description: Filter vulnerabilities on hasKev. Accepts `true` or `false`.
schema:
type: boolean
example: true
- in: query
name: isExempted
description: >-
Filter vulnerabilities based on exemptions. Returns exempted
vulnerabilities if set true. Accepts `true` or `false`.
schema:
type: boolean
example: true
default: false
- in: query
name: isExploitable
description: >-
Filter vulnerabilities based on exploitability under the Common
Vulnerability Scoring System (CVSS). Accepts `true` or `false`.
schema:
type: boolean
example: true
- in: query
name: hasExploit
description: Filter vulnerabilities on hasExploit. Accepts `true` or `false`.
schema:
type: boolean
example: true
- in: query
name: hasVendorFix
description: >-
Filter vulnerabilities where the affected packages have a fixed
version. Is true if any affected package has a fixed version.
Accepts `true` or `false`.
schema:
type: boolean
example: true
- in: query
name: severityLevels
description: Filter vulnerabilities on severity. Accepts a comma-separated list.
schema:
type: string
enum:
- CRITICAL
- HIGH
- MEDIUM
- LOW
- INFORMATIONAL
- UNKNOWN
example: CRITICAL,HIGH
- in: query
name: firstObservedAtStart
description: >-
Start of the date range for filtering vulnerabilities based on the
first observed time.
Specify the start of the range using a valid ISO 8601 date-time
string.
If `firstObservedAtStart` is provided and `firstObservedAtEnd` is
omitted,
results will include vulnerabilities observed from this date to the
present.
Supported formats include:
- `yyyy-MM-ddTHH:mm:ssZ` (e.g., `2020-12-18T08:00:00Z`)
- `yyyy-MM-ddTHH:mm:ss.SSSZ` (e.g., `2020-12-18T08:00:00.000Z`)
schema:
type: string
format: date-time
example: '2023-02-01T18:09:07Z'
- in: query
name: firstObservedAtEnd
description: >-
End of the date range for filtering vulnerabilities based on the
first observed time.
Specify the end of the range using a valid ISO 8601 date-time
string.
If `firstObservedAtEnd` is provided and `firstObservedAtStart` is
omitted,
results will include vulnerabilities observed up to this date.
Supported formats include:
- `yyyy-MM-ddTHH:mm:ssZ` (e.g., `2020-12-18T08:00:00Z`)
- `yyyy-MM-ddTHH:mm:ss.SSSZ` (e.g., `2020-12-18T08:00:00.000Z`)
schema:
type: string
format: date-time
example: '2023-02-01T18:09:07Z'
- in: query
name: sortBy
description: Sort results by the specified field.
schema:
type: string
enum:
- hasKev
- hasExploit
- lastObservedAt
- firstObservedAt
- severityLevelValue
example: hasExploit
- in: query
name: sortOrder
description: Sort order for the results.
schema:
type: string
enum:
- ASC
- DESC
example: ASC
- in: query
name: page
description: Page number for the results. Accepts a positive integer.
schema:
type: integer
example: 10
default: 1
minimum: 1
- in: query
name: perPage
description: Number of results per page. Accepts a positive integer.
schema:
type: integer
example: 50
default: 100
maximum: 2000
- in: query
name: cursor
description: >-
Get the next batch of vulnerabilities. Used for pagination. When
cursor is provided, the response will not include total count.
schema:
type: string
- in: query
name: includeTotal
description: >-
Include the total count of available vulnerabilities. Defaults to
true. Set to false to improve response times for large datasets.
schema:
type: boolean
default: true
example: true
responses:
'200':
description: Successful response with the list of vulnerabilities
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
schemaVersion:
type: string
example: '2022-06-09'
assetId:
type: string
example: prn:assets:a
organizationId:
type: string
example: 98ca8825-a65a-4b50-a6f0-4851c406aedc
tenantId:
type: string
example: 98ca8825-a65a-4b50-a6f0-4851c406aedc
integrationId:
type: string
example: 98ca8825-a65a-4b50-a6f0-4851c406aedc
vulnerabilityId:
type: string
example: CVE-2022-22965
provider:
type: string
example: AWS
assetType:
type: string
example: AWS::EC2::Instance
description:
type: string
example: A flaw was found in shadow-utils.
severityLevel:
type: string
example: HIGH
firstObservedAt:
type: string
example: '2023-10-27T04:54:37.830Z'
lastObservedAt:
type: string
example: '2023-10-27T04:54:37.830Z'
publishedDate:
type: string
example: '2023-10-27T04:54:37.830Z'
executionId:
type: string
example: '1678607803935'
title:
type: string
example: Sample Vulnerability Title
targetName:
type: string
example: EcsTaskDefinition:15 > nginx:1.19.1-alpine-perl
severitySource:
type: string
example: redhat
primaryUrl:
type: string
example: https://nvd.nist.gov/vuln/detail/CVE-2022-22965
packages:
type: array
items:
type: object
properties:
packageName:
type: string
example: sample-package
targetName:
type: string
example: >-
EcsTaskDefinition:15 >
nginx:1.19.1-alpine-perl
targetType:
type: string
example: sample-target-type
targetPath:
type: string
example: >-
ip-172-31-29-14.ap-southeast-2.compute.internal
targetClass:
type: string
example: os-pkgs
fixedVersion:
type: string
example: 1.0.1
installedVersion:
type: string
example: 1.0.0
cwes:
type: array
items:
type: object
properties:
id:
type: string
example: '1'
name:
type: string
example: CWE-123
cweId:
type: string
example: CWE-123
source:
type: string
example: MITRE
sourceUrl:
type: string
example: https://example.com/cwe/CWE-123
description:
type: string
example: This is a sample CWE description.
hasKev:
type: boolean
example: true
hasExploit:
type: boolean
example: false
hasVendorFix:
type: boolean
example: true
knownExploit:
oneOf:
- type: 'null'
- type: object
properties:
id:
type: string
example: '1'
title:
type: string
example: Sample Exploit Title
description:
type: string
example: This is a sample exploit description.
source:
type: string
example: MITRE
sourceUrl:
type: string
example: https://example.com/exploit/CVE-2023-12345
example:
cveID: CVE-2022-22965
notes: ''
dueDate: '2022-04-25'
product: Spring Framework
dateAdded: '2022-04-04'
vendorProject: VMware
requiredAction: Apply updates per vendor instructions.
shortDescription: >-
Spring MVC or Spring WebFlux application
running on JDK 9+ may be vulnerable to remote
code execution (RCE) via data binding.
vulnerabilityName: >-
Spring Framework JDK 9+ Remote Code Execution
Vulnerability
exploits:
type: array
items:
type: object
properties:
id:
type: string
example: '1'
title:
type: string
example: Sample Exploit Title
description:
type: string
example: This is a sample exploit description.
source:
type: string
example: MITRE
sourceUrl:
type: string
example: https://example.com/exploit/CVE-2023-12345
exemptions:
oneOf:
- type: 'null'
- type: array
items:
type: object
properties:
exemptionId:
type: string
format: uuid
example: e26380da-946e-496e-bebe-9774dae93ed5
exemption:
type: object
properties:
name:
type: string
reason:
type: string
enum:
- ACCEPTED_RISK
- COMPENSATING_CONTROL
- NO_VENDOR_FIX
- NOT_IN_USE
- OTHER_REASONS
rules:
type: array
items:
type: object
properties:
exemptionType:
type: string
enum:
- ASSET_VULNERABILITY
- BULK_EXEMPTION
vulnerabilityId:
oneOf:
- type: 'null'
- type: string
vulnerabilityIds:
oneOf:
- type: 'null'
- type: array
items:
type: string
assetIds:
oneOf:
- type: 'null'
- type: array
items:
type: string
assetRegions:
oneOf:
- type: 'null'
- type: array
items:
type: string
assetGroupIds:
oneOf:
- type: 'null'
- type: array
items:
type: string
format: uuid
assetTags:
oneOf:
- type: 'null'
- type: array
items:
type: object
properties:
key:
type: string
value:
type: string
noVendorFix:
type: boolean
format: nullable
example: true
createdAt:
type: string
updatedAt:
type: string
example:
- exemptionId: e26380da-946e-496e-bebe-9774dae93ed5
exemption:
name: exemption-rule-001
reason: ACCEPTED_RISK
createdAt: '2025-06-05T04:54:49.495Z'
updatedAt: '2025-06-05T04:54:49.495Z'
rules:
- exemptionType: ASSET_VULNERABILITY
vulnerabilityId: CVE-2025-12345
vulnerabilityIds:
- CVE-2025-12345
assetIds:
- >-
prn:assets:c00720a1-c167-4fbf-87ea-b6172949b62d:aws:ec2:instance:ap-southeast-2:i-02dd74c78250f9f1a
assetGroupIds:
- e26380da-946e-496e-bebe-9774dae93ed5
assetRegions:
- ap-southeast-2
assetTags:
- key: Owner
value: TeamOne
noVendorFix: false
severityLevelValue:
type: integer
example: 4
meta:
type: object
properties:
perPage:
type: number
cursor:
type: string
description: Cursor for fetching the next page of results
page:
type: number
description: >-
Present only when includeTotal is true and cursor is
not provided
total:
type: number
description: >-
Total number of vulnerabilities. Present only if
includeTotal is set to true
hasNextPage:
type: boolean
description: >-
Present only when includeTotal is true and cursor is
not provided
hasPreviousPage:
type: boolean
description: >-
Present only when includeTotal is true and cursor is
not provided
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
example: Expected string to be a number, got abc123
examples:
example-0:
summary: Invalid sortBy
description: Response when sortBy is invalid
value:
errors:
- message: >-
sortBy must be one of the following: id,
vulnerabilityId, severityLevel, severitySource,
hasKev, hasExploit, file, createdAt, updatedAt
example-1:
summary: Invalid page
description: Response when page is invalid
value:
errors:
- message: page must be a positive integer
example-2:
summary: Invalid perPage
description: Response when perPage is invalid
value:
errors:
- message: >-
perPage must be a positive integer less than or equal
to 1000
example-3:
summary: sortOrder requires sortBy
description: Response when sortBy is not provided to use sortOrder
value:
errors:
- message: sortBy must be provided to use sortOrder
example-4:
summary: Invalid sortOrder
description: Response when sortOrder is invalid
value:
errors:
- message: >-
sortOrder must be either asc or desc (case
insensitive)
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
security:
- APIKey: []
components:
parameters:
paramAuthHeader:
name: Authorization
in: header
description: Bearer API Key. For example, "Bearer {Tenant API Key}"
required: true
schema:
type: string
schemas:
InternalServerErrorResponse:
type: object
properties:
message:
type: string
example: Internal server error
securitySchemes:
APIKey:
type: http
scheme: bearer
bearerFormat: apiKey
description: Bearer API Key. For example, "Bearer {Tenant API Key}"
````