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.
- name: Metrics
x-displayName: Metrics
description: >-
The time series behind the Plerion dashboards, such as finding, asset,
risk and alert counts, posture scores and Plerion unit consumption,
queried by namespace and metric name over a period.
- name: Workload scans
x-displayName: Workload Scans
description: >-
Request a scan of one workload now, ahead of the schedule, and follow its
status.
paths:
/v1/tenant/ownership/rules:
put:
tags:
- Ownership
summary: Set rules
description: >-
Replaces the tenant's ownership rules with this list, in this order,
then works out every asset's owners again in the background. The
response does not wait for that: follow its progress in `scan` on [Get
ownership summary](/api-reference/ownership/get-summary).
Every value a rule's tag holds becomes an owner, a team or a person.
Plerion decides the kind per value (emails are people, group names and
tools are teams) unless the rule sets `always`. Send `owners` to settle
the kind of particular values, as the setup in the Plerion app does.
The list replaces every rule, so start from [List ownership
rules](/api-reference/ownership/list-rules) and send its rules back with
your change. Send its `version` too (in the body or as an `If-Match`
header): if the rules changed since you read them, the request is
refused (`409 RulesChanged`) and nothing is saved. Without `version` the
list is saved as sent.
A tag with more than 2,000 different values is refused
(`TooManyValues`): that many values are IDs, not owners. One owner tag
per key and side (`DuplicateRule`). An additional rule must name a team
or person that exists (`OwnerNotFound`). Requires
`OwnershipRule:Modify`.
operationId: setOwnershipRules
parameters:
- $ref: '#/components/parameters/paramAuthHeader'
- in: header
name: Content-Type
description: application/json
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- rules
properties:
rules:
type: array
maxItems: 220
description: >-
The rules in priority order, first wins. Rules read only
from integration tags are moved after the rest, so an
asset's own tags are always tried first. Whatever the order,
an `assign` rule with `overrideTags` is tried before the
owner tags, and one without it after them. At most 20 owner
tags and 200 additional rules. Keep a rule's `id` to keep
the owners it found linked to it.
items:
$ref: '#/components/schemas/OwnershipRuleInput'
version:
$ref: '#/components/schemas/OwnershipRulesVersion'
owners:
type: array
maxItems: 500
description: >-
Optional. The kind of particular values, overriding
Plerion's guess.
items:
type: object
required:
- value
- kind
properties:
value:
type: string
description: A tag value, as it appears on assets
example: payments
kind:
$ref: '#/components/schemas/OwnerKind'
key:
type: string
description: The tag key the value was read from
example: Team
from:
type: string
description: Where that tag was read
enum:
- asset
- integration
example:
version: 9mQx2bTq4kLr7sVw1yZa0c
rules:
- type: tag
enabled: true
config:
key: Team
from: asset
newOwnersAre: team
- type: tag
enabled: true
config:
key: Owner
from: asset
newOwnersAre: person
owners:
- value: sre-oncall@example.com
kind: team
key: Owner
responses:
'200':
description: The rules as saved
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
rules:
type: array
items:
$ref: '#/components/schemas/OwnershipRule'
version:
$ref: '#/components/schemas/OwnershipRulesVersion'
'400':
$ref: '#/components/responses/OwnershipError'
'403':
$ref: '#/components/responses/403'
'409':
$ref: '#/components/responses/OwnershipError'
'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
schemas:
OwnershipRuleInput:
type: object
description: >-
One rule. `tag` rules (owner tags) read an owner from a tag's value.
`assign` rules (additional rules) give the assets matching their
conditions to one team or person. `tagValue` is the custom rule saved
before conditions existed: still accepted and read as before, but new
rules should use `assign`.
required:
- type
- config
properties:
id:
type: string
format: uuid
description: Keep an existing rule's ID when sending it back
type:
type: string
enum:
- tag
- assign
- tagValue
enabled:
type: boolean
default: true
config:
oneOf:
- $ref: '#/components/schemas/OwnershipTagRuleConfig'
- $ref: '#/components/schemas/OwnershipAssignRuleConfig'
- $ref: '#/components/schemas/OwnershipValueRuleConfig'
OwnershipRulesVersion:
type: string
description: >-
The version of the whole rule list. It changes whenever any rule is
added, removed, moved or edited. Send it back with a change so a change
made meanwhile is not overwritten.
example: 9mQx2bTq4kLr7sVw1yZa0c
OwnerKind:
type: string
description: An asset has at most one team owner and one person owner.
enum:
- team
- person
OwnershipRule:
allOf:
- $ref: '#/components/schemas/OwnershipRuleInput'
- type: object
properties:
priority:
type: integer
example: 1
origin:
type: string
description: >-
`detected`: an owner tag Plerion added from your tags. It
becomes `custom` once you change it.
enum:
- detected
- custom
updatedBy:
type: string
nullable: true
updatedAt:
type: string
format: date-time
OwnershipTagRuleConfig:
type: object
title: Owner tag (type tag)
required:
- key
- from
- newOwnersAre
properties:
key:
type: string
maxLength: 500
description: >-
The tag key. Case and separators are ignored, so `Owner` also reads
`owner`.
example: Team
from:
type: string
description: >-
Where the tag is read: on the asset, on the asset's integration
(such as the tags on an AWS account), or `both`. Every tag read on
the asset is tried before any tag read only on the integration, so
an asset's own tag wins over its integration's. A key can be read
once on each side.
enum:
- asset
- integration
- both
newOwnersAre:
$ref: '#/components/schemas/OwnerKind'
always:
type: boolean
description: >-
Every value of this tag is `newOwnersAre`, with no guessing. Without
it, Plerion decides per value and `newOwnersAre` is the fallback for
plain names.
ignoreValues:
type: array
maxItems: 500
description: >-
Values of this tag that name nobody. An asset with one of them is
read as having no value, so the next rule gets its turn.
items:
type: string
keepValues:
type: array
maxItems: 500
description: >-
Values Plerion would read as naming nobody (such as a tool name)
that are owners in this tag.
items:
type: string
OwnershipAssignRuleConfig:
type: object
title: Additional rule (type assign)
description: >-
The assets matching the conditions belong to one team or person. An
asset must match every condition, except name conditions, where matching
any one is enough. An owner tag that names someone wins over the rule,
unless `overrideTags` is true.
required:
- when
- ownerId
properties:
ownerId:
type: string
format: uuid
description: The team or person the matching assets belong to. It must exist.
when:
type: array
minItems: 1
maxItems: 10
items:
$ref: '#/components/schemas/OwnershipRuleCondition'
overrideTags:
type: boolean
description: >-
True to give the matching assets to this owner even when an owner
tag names someone else. Leave it out for a rule that only fills the
gaps owner tags leave.
example:
ownerId: 3f0c1b6e-6b1f-4b5e-9f7a-2a1d4c8e9b10
when:
- type: resourceType
value:
- AWS::S3::Bucket
- type: region
value:
- ap-southeast-2
- type: resourceName
operator: startsWith
value: payments-
OwnershipValueRuleConfig:
type: object
title: Custom rule saved before conditions (type tagValue)
description: >-
Assets whose tag `key` has one of `values`, or matches `pattern` (`*` is
any text), belong to `ownerId`. Use `assign` for new rules; this shape
is kept so rules saved with it go on working.
required:
- key
- from
- ownerId
properties:
key:
type: string
maxLength: 500
from:
type: string
enum:
- asset
- integration
values:
type: array
maxItems: 500
items:
type: string
pattern:
type: string
maxLength: 200
ownerId:
type: string
format: uuid
InternalServerErrorResponse:
type: object
properties:
message:
type: string
example: Internal server error
OwnershipRuleCondition:
type: object
description: >-
One thing an asset must have.
- `tag`: the tag `key`, read on the asset or its integration (`from`),
has one of `values`. Values compare with case and separators ignored; a
value with `*` matches any text in its place, so `sand*` matches
`sandbox`.
- `integration`, `resourceType`, `region`: the asset's integration ID,
resource type or region is one of `value`.
- `resourceName`: the asset's name `equals`, `startsWith`, `endsWith` or
`contains` `value`. Names compare with case.
required:
- type
properties:
type:
type: string
enum:
- tag
- integration
- resourceType
- region
- resourceName
from:
type: string
description: For `tag`
enum:
- asset
- integration
key:
type: string
maxLength: 500
description: For `tag`
example: Purpose
values:
type: array
minItems: 1
maxItems: 500
description: For `tag`
items:
type: string
example:
- sandbox*
operator:
type: string
description: For `resourceName`
enum:
- equals
- startsWith
- endsWith
- contains
value:
description: >-
A list of 1 to 500 for `integration`, `resourceType` and `region`; a
name of at most 500 characters for `resourceName`.
oneOf:
- type: array
minItems: 1
maxItems: 500
items:
type: string
- type: string
maxLength: 500
responses:
'403':
description: Forbidden
content:
application/json:
schema:
properties:
message:
type: string
example: Forbidden
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
OwnershipError:
description: >-
The request was refused. `code` says why, for example `InvalidRequest`,
`NotFound`, `NameTaken`, `OwnerLimitReached`, `KindMismatch`,
`TooManyValues`, `DuplicateRule`, `OwnerNotFound`, `OriginValue`,
`RulesChanged` or `SettingsChanged`.
content:
application/json:
schema:
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
example: NameTaken
message:
type: string
example: >-
Payments already goes by "payments". Use that one
instead.
securitySchemes:
APIKey:
type: http
scheme: bearer
bearerFormat: apiKey
description: Bearer API Key. For example, "Bearer {Tenant API Key}"
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.