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/assets:
get:
tags:
- Assets
summary: List
description: >-
Use the list assets API to filter assets across the tenant with many
options from Provider, Service, Severity, Integration, etc. By default
all assets are returned.
operationId: listTenantAssets
parameters:
- $ref: '#/components/parameters/paramAuthHeader'
- in: header
name: Content-Type
description: application/json
schema:
type: string
- in: query
name: ids
description: Filter assets based on Asset IDs. Accepts a comma-separated list.
schema:
type: string
example: id1,id2
- in: query
name: executionIds
description: >-
Filter assets based on Integration Execution IDs. Accepts a
comma-separated list.
schema:
type: string
example: 1678607803935,1778607801234
- in: query
name: regions
description: >-
Filter assets based on Provider regions. Accepts a comma-separated
list of regions.
schema:
type: string
example: us-east-1,us-west-2
- in: query
name: integrationIds
description: >-
Filter assets based on Plerion Integration IDs. Accepts a
comma-separated list.
schema:
type: string
example: integration1,integration2
- in: query
name: assetGroupIds
description: >-
Filter assets based on asset group ids. Accepts a comma-separated
list of asset group ids.
schema:
type: string
example: assetGroupId1,assetGroupId2
- in: query
name: environmentIds
description: >-
Filter assets based on environment IDs. This parameter accepts both
environment IDs (UUIDs) and environment names.
**Supported environment names:**
- `production` - Production environment
- `non-production` - Non-production environment
You can provide either environment IDs, environment names, or a
combination of both.
schema:
type: string
example: production,550e8400-e29b-41d4-a716-446655440000
- in: query
name: severityLevels
description: >-
Filter assets based on vulnerability severity levels. Accepts a
comma-separated list of severity levels.
schema:
type: string
enum:
- CRITICAL
- HIGH
- MEDIUM
- LOW
example: CRITICAL,HIGH
- in: query
name: secretsLevels
description: >-
Filter assets based on exposed secrets severity levels. Accepts a
comma-separated list of severity levels.
schema:
type: string
enum:
- CRITICAL
- HIGH
- MEDIUM
- LOW
example: CRITICAL,HIGH
- in: query
name: resourceTypes
description: >-
Filter assets based on provider resource types. Accepts a
comma-separated list of resource types.
schema:
type: string
example: AWS::S3::Bucket,AWS::Lambda::Function
- in: query
name: providers
description: >-
Filter assets based on provider. Accepts a comma-separated list of
providers.
schema:
type: string
enum:
- AWS
- Azure
- GCP
- Kubernetes
example: AWS,GCP
- in: query
name: services
description: >
Filter assets based on cloud provider services. Accepts a
comma-separated list of service names. Each service can be specified
either by its name alone (e.g., `S3`, `Lambda`, `EC2`) or prefixed
with its provider in the format `Provider::Service` (e.g.,
`AWS::S3`, `GCP::Compute`, `Azure::VirtualMachine`).
schema:
type: string
example: AWS::S3,GCP::Compute,Azure::VirtualMachine
- in: query
name: firstObservedAtStart
description: >-
Start of the date range for filtering assets 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 assets 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 assets 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 assets 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: hasAdminPrivileges
description: >-
Filter assets based on whether the asset has Admin Privileges. The
supported values are `true` or `false`
schema:
type: string
format: boolean
example: true
- in: query
name: hasOverlyPermissivePrivileges
description: >-
Filter assets based on whether the asset has Overly Permissive
Privileges. The supported values are `true` or `false`
schema:
type: string
format: boolean
example: true
- in: query
name: isSusceptibleToPrivilegeEscalation
description: >-
Filter assets based on whether the asset is susceptible to privilege
escalation. The supported values are `true` or `false`
schema:
type: string
format: boolean
example: true
- in: query
name: hasKev
description: >-
Filter assets based on whether the asset has any unresolved
vulnerability that is found on the CISA's Known Exploited
Vulnerabilities Catalog. The supported values are `true` or `false`
schema:
type: string
format: boolean
example: true
- in: query
name: hasExploit
description: >-
Filter assets based on whether the asset has any unresolved
vulnerability that is referenced on the MITRE Exploit-DB reference
map. The supported values are `true` or `false`
schema:
type: string
format: boolean
example: true
- in: query
name: isExploitable
description: >-
Filter assets based on whether the asset has any unresolved
vulnerability that has a CVSS v3 exploitability score greater than
1. The supported values are `true` or `false`
schema:
type: string
format: boolean
example: true
- in: query
name: isPubliclyExposed
description: >-
Filter assets based on whether the asset is Publicly Accessible. The
supported values are `true` or `false`
schema:
type: string
format: boolean
example: true
- in: query
name: isVulnerable
description: >-
Filter assets based on whether the asset has any unresolved
vulnerability regardless of severity, source, or status. The
supported values are `true` or `false`
schema:
type: string
format: boolean
example: true
- in: query
name: query
description: Filter assets based on the Asset's name matching the provided value
schema:
type: string
example: test-asset-name
- in: query
name: metadata
description: >-
Filter assets based on the asset's metadata matching the provided
value. The search performs a case-insensitive substring match
against all metadata keys and values, including nested fields.
schema:
type: string
example: t2.micro
- in: query
name: riskScoreGte
description: >-
Filter assets based on the risk score calculated by Plerion for the
asset. The supported values are numbers from 0 to 10.
schema:
type: string
format: number
example: 5
- in: query
name: operationalStates
description: >
Filter assets based on their operational state. Accepts a
comma-separated list of operational states.
Supported values:
- `active` — running workloads
- `inactive` — not running workloads
Supported resource types:
- AWS EC2 Instance — `active` indicates the instance is in a `running` state; `inactive` indicates it is `stopped` or `terminated`.
When this filter is applied, only assets belonging to resource types
that support operational state are returned.
schema:
type: string
enum:
- active
- inactive
example: active
- in: query
name: sortBy
description: Order the list by supported field
schema:
type: string
enum:
- id
- executionId
- integrationId
- resourceType
- service
- region
- name
- provider
- firstObservedAt
- lastObservedAt
- riskScore
- vulnerabilityScore
- numberOfLowVulnerabilities
- numberOfMediumVulnerabilities
- numberOfHighVulnerabilities
- numberOfCriticalVulnerabilities
example: executionId
- in: query
name: sortOrder
description: >-
The sort order of the list. The parameter sortBy has to be provided
to use sortOrder. If sortOrder is not provided the default order is
`ASC`
schema:
type: string
enum:
- ASC
- DESC
example: ASC
- in: query
name: page
description: Get the next batch of assets. Used for pagination
schema:
type: number
minimum: 1
example: 2
- in: query
name: perPage
description: Specify the batch size of the list. Used for pagination
schema:
type: number
example: 100
maximum: 1000
responses:
'200':
description: Assets list
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Asset'
meta:
$ref: '#/components/schemas/ListMeta'
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:
Asset:
type: object
properties:
schemaVersion:
type: string
example: '2022-06-09'
id:
type: string
example: >-
prn:assets:afeb4e5f-0370-4b43-8e37-7e4efc719358:aws:ec2:instance:ap-southeast-2:i-085a328dba59f229b
organizationId:
type: string
example: dc16d897-7f52-4b73-be57-96c7c9a853da
tenantId:
type: string
example: 42749bc1-c99b-4c2c-a081-a6cda9370081
integrationId:
type: string
example: 458511a1-9bc2-4fce-97a0-0e3139588e6e
executionId:
type: string
example: 1675576960384
provider:
type: string
example: AWS
type:
type: string
example: AWS::EC2::Instance
name:
oneOf:
- type: string
- type: 'null'
example: i-085a328dba59f229b
createdAt:
oneOf:
- type: string
- type: 'null'
example: '2023-02-04T06:07:09.092Z'
firstObservedAt:
oneOf:
- type: string
- type: 'null'
example: '2023-02-04T06:02:40.594Z'
lastObservedAt:
oneOf:
- type: string
- type: 'null'
example: '2023-02-05T06:02:40.384Z'
updatedAt:
oneOf:
- type: string
- type: 'null'
example: '2023-02-05T06:07:02.959Z'
tags:
oneOf:
- type: array
items:
type: object
properties:
Key:
type: string
description: Name of the Tag's Key
example: Department
Value:
type: string
description: Value of the Tag's Key
example: Finance
- type: 'null'
isPubliclyExposed:
oneOf:
- type: boolean
- type: 'null'
example: false
isVulnerable:
oneOf:
- type: boolean
- type: 'null'
example: false
numberOfLowVulnerabilities:
oneOf:
- type: number
- type: 'null'
example: 85
numberOfMediumVulnerabilities:
oneOf:
- type: number
- type: 'null'
example: 60
numberOfHighVulnerabilities:
oneOf:
- type: number
- type: 'null'
example: 15
numberOfCriticalVulnerabilities:
oneOf:
- type: number
- type: 'null'
example: 5
vulnerabilityScore:
oneOf:
- type: string
- type: 'null'
example: 9
hasKev:
oneOf:
- type: boolean
- type: 'null'
example: false
hasExploit:
oneOf:
- type: boolean
- type: 'null'
example: false
isExploitable:
oneOf:
- type: boolean
- type: 'null'
example: false
isInVpc:
oneOf:
- type: boolean
- type: 'null'
example: false
lastScanId:
oneOf:
- type: string
- type: 'null'
example: 1679594910265
lastScannedAt:
oneOf:
- type: string
- type: 'null'
example: '2023-03-23T18:17:20.003Z'
imageId:
oneOf:
- type: string
- type: 'null'
platform:
oneOf:
- type: string
- type: 'null'
hasAdminPrivileges:
oneOf:
- type: boolean
- type: 'null'
example: false
hasOverlyPermissivePrivileges:
oneOf:
- type: boolean
- type: 'null'
example: false
hasAuthorizer:
oneOf:
- type: boolean
- type: 'null'
example: false
hasTracingEnabled:
oneOf:
- type: boolean
- type: 'null'
example: false
policy:
oneOf:
- $ref: '#/components/schemas/DynamicObject'
type: object
- type: 'null'
numberOfLowSecrets:
oneOf:
- type: number
- type: 'null'
example: 3
numberOfMediumSecrets:
oneOf:
- type: number
- type: 'null'
example: 1
numberOfHighSecrets:
oneOf:
- type: number
- type: 'null'
example: 0
numberOfCriticalSecrets:
oneOf:
- type: number
- type: 'null'
example: 2
lowSecrets:
oneOf:
- $ref: '#/components/schemas/DynamicObjectArray'
- type: 'null'
mediumSecrets:
oneOf:
- $ref: '#/components/schemas/DynamicObjectArray'
- type: 'null'
highSecrets:
oneOf:
- $ref: '#/components/schemas/DynamicObjectArray'
- type: 'null'
criticalSecrets:
oneOf:
- $ref: '#/components/schemas/DynamicObjectArray'
- type: 'null'
operatingSystem:
oneOf:
- type: array
items:
$ref: '#/components/schemas/OperatingSystem'
- type: 'null'
riskScore:
oneOf:
- type: string
- type: 'null'
example: 9.36
operationalState:
type: string
enum:
- active
- inactive
description: >
The operational state of the resource. Present only for resource
types that support operational state.
Supported resource types: AWS EC2 Instance.
example: active
region:
type: string
example: us-east-1
service:
type: string
example: AWS::EC2
resourceId:
type: string
example: i-085a328dba59f229b
resourceName:
type: string
example: test-instance
resourceTags:
oneOf:
- type: array
items:
type: object
properties:
Key:
type: string
example: Public
Value:
type: string
example: true
- type: 'null'
resourceType:
type: string
example: AWS::EC2::Instance
fullResourceName:
type: string
example: arn:aws:iam::1111222233334444:policy/test-policy
providerAccountId:
type: string
example: 123456789012
resourceURL:
type: string
example: >-
https://us-east-1.console.aws.amazon.com/iam/home#/policies/arn:aws:iam::1111222233334444:policy/test-policy
ListMeta:
type: object
properties:
page:
type: integer
example: 1
perPage:
type: integer
example: 100
total:
type: integer
example: 200
hasNextPage:
type: boolean
example: true
hasPreviousPage:
type: boolean
example: false
DynamicObject:
type: object
additionalProperties:
type: string
DynamicObjectArray:
type: array
items:
$ref: '#/components/schemas/DynamicObject'
OperatingSystem:
type: object
properties:
architecture:
type: string
description: The architecture of the operating system.
example: x86_64
name:
type: string
description: The name of the operating system.
example: Ubuntu
platform:
type: string
description: The OS platform.
example: Linux/UNIX
version:
type: string
description: The version of the operating system including version name.
example: 24.04.2 LTS (Noble Numbat)
versionId:
type: string
description: The version of the operating system.
example: 24.04
activeKernel:
type: string
description: The kernel version of the operating system.
example: 4.14.246-197.484.amzn2.x86_64
buildNumber:
type: string
description: The build number of the windows operating system.
example: 20348.fe_release.210507-1500
lcuVersion:
type: string
description: The latest cumulative update version of the windows operating.
example: 10.0.20348.2762
securitySchemes:
APIKey:
type: http
scheme: bearer
bearerFormat: apiKey
description: Bearer API Key. For example, "Bearer {Tenant API Key}"
````