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. |
| 412 | Precondition Failed | The resource changed after the version supplied in the If-Match header. Read the resource again and retry the request with the version returned. |
| 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')
# 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')
# Fetch the tenant ID
export TENANT_ID=$(curl -s -X GET "https://$PLERION_API_URL/v1/tenant" -H "Authorization: Bearer $PLERION_API_KEY" | jq -r '.data.tenantId')
# 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=TenantId,ParameterValue=$TENANT_ID \
ParameterKey=Capabilities,ParameterValue=ALL \
ParameterKey=KMSKeyAccessMode,ParameterValue="ALL_KEYS"
# 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')
# 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')
# Fetch the tenant ID
export TENANT_ID=$(curl -s -X GET "https://$PLERION_API_URL/v1/tenant" -H "Authorization: Bearer $PLERION_API_KEY" | jq -r '.data.tenantId')
# 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=TenantId,ParameterValue=$TENANT_ID \
ParameterKey=Capabilities,ParameterValue=ALL \
ParameterKey=KMSKeyAccessMode,ParameterValue="ALL_KEYS"
# 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: Code security
x-displayName: Code Security
description: >-
Code security scans infrastructure-as-code before it reaches a cloud
environment, so a misconfiguration is caught in the pull request rather
than after deployment.
Upload a Terraform, CloudFormation or Kubernetes archive to start a scan,
then retrieve the findings it produced and any vulnerabilities detected in
container images the templates reference.
- 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.
- name: AWS access grants
x-displayName: Access Grants
description: >-
An access grant records the access that one of your AWS resources gives to
a single principal. Plerion derives grants from resource policies, IAM
role trust policies, AWS Resource Access Manager shares and cross-account
share attributes, capturing the principal, the actions allowed and any
conditions attached. Use these endpoints to pull the inventory into your
own audits or SIEM, and to record review decisions without signing in to
Plerion.
paths:
/v1/tenant/profiles/{profileId}/detection-settings/{detectionId}/exemptions:
put:
tags:
- Detection exemptions
summary: Replace
description: >-
Replace the whole exemption set for one detection on one profile. The
body is the set you want to end up with, so read the current set, change
it, and send all of it back. An empty array clears the set; there is no
endpoint for a single entry and no exemption ID.
Send the `version` from the read as `If-Match`. The write is then
rejected with a `412` (`VersionMismatch`) if the detection's
configuration changed in the meantime, so re-read and retry. Without the
header the write applies unconditionally: a concurrent change is
overwritten and no `412` is returned. Send it whenever the read returned
a version, and omit it only when `version` was `null`, since there is
then no stored configuration to match against.
`version` covers the detection's whole configuration, not just its
exemptions, so a change to its severity or parameters also invalidates
it. Saving the profile in the Plerion platform rewrites every detection
configured on it, which invalidates any version held against that
profile.
A non-empty set is rejected with a `400` when the detection does not
accept exemptions (`ExemptionsNotSupported`) or when an entry's `type`
is outside the detection's `supportedExemptionTypes`
(`UnsupportedExemptionType`). Both would otherwise be stored and then
never take effect. Clearing is always allowed, whatever the detection
supports today.
Only the exemptions change. A severity override or parameter set on the
same detection is left alone, and exemptions written here apply to
findings Plerion has already stored rather than waiting for the next
scan.
operationId: replaceDetectionExemptions
parameters:
- $ref: '#/components/parameters/paramAuthHeader'
- in: header
name: Content-Type
description: application/json
schema:
type: string
- in: header
name: If-Match
description: >-
The `version` returned by the read, echoed back unchanged. When
supplied, the write is rejected with a `412` unless it still matches
the stored value. When omitted, the write applies unconditionally.
Omit it only when the detection has no stored configuration on the
profile yet.
schema:
type: string
- $ref: '#/components/parameters/paramProfileId'
- $ref: '#/components/parameters/paramDetectionId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- exemptions
additionalProperties: false
properties:
exemptions:
type: array
description: >-
The complete exemption set for the detection. Send an empty
array to clear it.
items:
$ref: '#/components/schemas/DetectionExemption'
responses:
'200':
description: Exemptions replaced
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/DetectionExemptionSet'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'412':
$ref: '#/components/responses/412'
'500':
$ref: '#/components/responses/500'
security:
- APIKey: []
components:
parameters:
paramAuthHeader:
name: Authorization
in: header
description: Bearer API Key. For example, "Bearer {Tenant API Key}"
required: true
schema:
type: string
paramProfileId:
name: profileId
in: path
description: >-
Profile ID, or the literal string `default` for the tenant's default
profile. `default` covers only the integrations that have not been given
a profile of their own, so on a tenant with more than one profile it
does not reach the rest. Use [List
profiles](/api-reference/profiles/list) to get the IDs.
required: true
schema:
type: string
example: default
paramDetectionId:
name: detectionId
in: path
description: >-
Detection ID. A finding reports the detection that produced it in its
`detectionId` field.
required: true
schema:
type: string
example: PLERION-AWS-16
schemas:
DetectionExemption:
description: >-
One exemption rule to write. The `type` decides which other fields
apply, and which types a detection accepts is reported by
`supportedExemptionTypes` on the read. The read returns
`StoredDetectionExemption`, which is looser.
oneOf:
- $ref: '#/components/schemas/NameExemption'
- $ref: '#/components/schemas/TagExemption'
- $ref: '#/components/schemas/RegionExemption'
- $ref: '#/components/schemas/PrincipalExemption'
- $ref: '#/components/schemas/RouteExemption'
discriminator:
propertyName: type
mapping:
NAME_EXEMPTION:
$ref: '#/components/schemas/NameExemption'
TAG_EXEMPTION:
$ref: '#/components/schemas/TagExemption'
REGION_EXEMPTION:
$ref: '#/components/schemas/RegionExemption'
PRINCIPAL_EXEMPTION:
$ref: '#/components/schemas/PrincipalExemption'
ROUTE_EXEMPTION:
$ref: '#/components/schemas/RouteExemption'
DetectionExemptionSet:
type: object
description: The exemptions configured for one detection on one profile.
required:
- profileId
- detectionId
- provider
- supportsExemptions
- supportedExemptionTypes
- exemptions
- version
properties:
profileId:
type: string
format: uuid
description: >-
The resolved profile ID. Requests addressed to `default` report the
ID the default profile resolved to.
example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
detectionId:
type: string
example: PLERION-AWS-16
provider:
type: string
description: The provider the detection belongs to.
example: AWS
supportsExemptions:
type: boolean
description: >-
Whether this detection accepts exemptions at all. A non-empty write
to one that does not is rejected with a `400`.
example: true
supportedExemptionTypes:
type: array
description: >-
The exemption types that can clear a finding from this detection.
Writing any other type is rejected, because it would be stored and
then never take effect. Empty when the detection does not support
exemptions.
items:
type: string
enum:
- NAME_EXEMPTION
- TAG_EXEMPTION
- REGION_EXEMPTION
- PRINCIPAL_EXEMPTION
- ROUTE_EXEMPTION
example:
- NAME_EXEMPTION
- TAG_EXEMPTION
- REGION_EXEMPTION
exemptions:
type: array
description: >-
The exemptions as stored. A detection that no longer supports
exemptions can still report entries written while it did.
items:
$ref: '#/components/schemas/StoredDetectionExemption'
version:
type:
- string
- 'null'
description: >-
An opaque token identifying the detection's current configuration.
Store it as a string and send it back unchanged as `If-Match` when
replacing the set. Do not parse it, compare two of them, or order by
it. The format is not part of this contract and can change. `null`
when the detection has never been configured on this profile, in
which case the replace request must omit the header.
NameExemption:
type: object
description: >-
Exempts assets whose name matches. Accepted by every detection that
supports exemptions, except Cloud Detection and Response (CDR)
detections.
required:
- type
- condition
- value
additionalProperties: false
properties:
type:
type: string
enum:
- NAME_EXEMPTION
reason:
$ref: '#/components/schemas/ExemptionReason'
condition:
type: string
description: >-
How `value` is compared with the asset name. These are the Equals,
Starts with, Ends with, and Contains options in the Plerion
platform.
enum:
- equals
- starts-with
- ends-with
- contains
example: starts-with
value:
type: string
description: >-
Must be non-empty unless `condition` is `equals`. On the other three
an empty value matches every asset name, which would exempt every
finding for the detection.
example: acme-sandbox-
allOf:
- if:
properties:
condition:
not:
const: equals
then:
properties:
value:
minLength: 1
TagExemption:
type: object
description: >-
Exempts assets carrying a matching tag. The key must match exactly; the
value can be matched loosely or ignored.
required:
- type
- tagKey
- tagValue
additionalProperties: false
properties:
type:
type: string
enum:
- TAG_EXEMPTION
reason:
$ref: '#/components/schemas/ExemptionReason'
tagKey:
type: object
required:
- option
- value
additionalProperties: false
properties:
option:
type: string
enum:
- equals
value:
type: string
example: environment
tagValue:
type: object
required:
- option
- value
additionalProperties: false
properties:
option:
type: string
description: >-
Use `any` to exempt every asset carrying the key, whatever its
value.
enum:
- equals
- starts-with
- ends-with
- contains
- any
value:
type: string
description: >-
Must be non-empty unless `option` is `any`, which ignores it, or
`equals`, which then matches only an empty tag value.
example: sandbox
allOf:
- if:
properties:
option:
not:
enum:
- any
- equals
then:
properties:
value:
minLength: 1
RegionExemption:
type: object
description: Exempts assets in the listed regions.
required:
- type
- regions
additionalProperties: false
properties:
type:
type: string
enum:
- REGION_EXEMPTION
reason:
$ref: '#/components/schemas/ExemptionReason'
regions:
type: array
items:
type: string
example:
- ap-southeast-2
- us-west-2
PrincipalExemption:
type: object
description: >-
Exempts findings raised against a matching principal. Only Cloud
Detection and Response (CDR) detections accept this type, because only
they report an actor rather than a misconfigured asset.
required:
- type
- condition
- value
additionalProperties: false
properties:
type:
type: string
enum:
- PRINCIPAL_EXEMPTION
reason:
$ref: '#/components/schemas/ExemptionReason'
condition:
type: string
enum:
- equals
- starts-with
- ends-with
- contains
example: equals
value:
type: string
description: >-
Must be non-empty unless `condition` is `equals`. On the other three
an empty value matches every principal.
example: arn:aws:iam::111122223333:role/deployment
allOf:
- if:
properties:
condition:
not:
const: equals
then:
properties:
value:
minLength: 1
RouteExemption:
type: object
description: >-
Exempts one API Gateway route. Accepted only by `PLERION-AWS-530` and
`PLERION-AWS-564`, which report a set of failing routes on one API
rather than a single verdict. The finding clears once every failing
route is exempted.
required:
- type
- apiId
- routeKey
additionalProperties: false
properties:
type:
type: string
enum:
- ROUTE_EXEMPTION
reason:
$ref: '#/components/schemas/ExemptionReason'
apiId:
type: string
example: a1b2c3d4e5
routeKey:
type: string
example: GET /health
createdBy:
type: string
description: >-
Set when the entry was created in the Plerion platform. Send it back
unchanged on an entry you read; omit it on a new one.
createdAt:
type: string
description: >-
Set when the entry was created in the Plerion platform. Send it back
unchanged on an entry you read; omit it on a new one.
StoredDetectionExemption:
type: object
description: >-
An exemption as stored. Send entries back unchanged when replacing the
set. The fields vary by `type`, and `DetectionExemption` documents which
belong to which.
required:
- type
additionalProperties: true
properties:
type:
type: string
enum:
- NAME_EXEMPTION
- TAG_EXEMPTION
- REGION_EXEMPTION
- PRINCIPAL_EXEMPTION
- ROUTE_EXEMPTION
reason:
$ref: '#/components/schemas/ExemptionReason'
condition:
type: string
example: starts-with
value:
type: string
example: acme-sandbox-
tagKey:
type: object
properties:
option:
type: string
example: equals
value:
type: string
example: environment
tagValue:
type: object
properties:
option:
type: string
example: equals
value:
type: string
example: test
regions:
type: array
items:
type: string
apiId:
type: string
routeKey:
type: string
createdBy:
type: string
createdAt:
type: string
InternalServerErrorResponse:
type: object
properties:
message:
type: string
example: Internal server error
ExemptionReason:
type: string
description: >-
Why the finding is being accepted. Optional; entries configured in the
Plerion platform may have none. Shown in the platform as Accepted risk,
False positive, and Compensating control.
enum:
- ACCEPTED_RISK
- FALSE_POSITIVE
- COMPENSATING_CONTROL
example: ACCEPTED_RISK
responses:
'400':
description: Bad Request
content:
application/json:
schema:
properties:
errors:
type: array
items:
type: object
properties:
field:
type: string
code:
type: string
message:
type: string
'404':
description: Not Found
content:
application/json:
schema:
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
message:
type: string
'412':
description: Precondition Failed
content:
application/json:
schema:
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
example: VersionMismatch
message:
type: string
example: >-
This detection was changed since the version you
supplied. Re-read the exemptions and retry.
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
securitySchemes:
APIKey:
type: http
scheme: bearer
bearerFormat: apiKey
description: Bearer API Key. For example, "Bearer {Tenant API Key}"
````