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/shiftleft/iac/scans/{scanId}/findings:
get:
tags:
- Code security
summary: List findings
description: Retrieve all the findings for a scanId
operationId: getIaCFindingsByScanId
parameters:
- $ref: '#/components/parameters/paramAuthHeader'
- in: header
name: Content-Type
description: application/json
schema:
type: string
- in: path
name: scanId
description: Scan ID
schema:
type: string
required: true
- in: query
name: ids
description: Filter findings based on ids. Accepts a comma-separated list of ids.
schema:
type: string
example:
- uuid1,uuid2,uuid3
- in: query
name: results
description: >-
Filter findings based on result. Accepts a comma-separated list of
result.
schema:
type: string
example:
- PASSED,FAILED
- in: query
name: detectionIds
description: >-
Filter findings based on detection id. Accepts a comma-separated
list of detection id.
schema:
type: string
example: PLERION-AWS-1,PLERION-AWS-2
- in: query
name: types
description: >-
Filter findings based on type. Accepts a comma-separated list of
type.
schema:
type: string
example: helm,kubernetes
- in: query
name: files
description: >-
Filter findings based on file. Accepts a comma-separated list of
file.
schema:
type: string
example: file1,file2
- in: query
name: severityLevels
description: >-
Filter findings based on severity. Accepts a comma-separated list of
severity.
schema:
type: string
enum:
- CRITICAL
- HIGH
- MEDIUM
- LOW
example: CRITICAL,HIGH
- in: query
name: sortBy
description: Sort results by the specified field.
schema:
type: string
enum:
- id
- createdAt
- updatedAt
- artifactName
- status
example: createdAt
- 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: 1
- in: query
name: perPage
description: Number of results per page. Accepts a positive integer.
schema:
type: integer
example: 10
responses:
'200':
description: OK
headers:
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
example: 12345678-86af-4fba-afc6-c0cf87654321
createdAt:
type: string
example: '2023-02-04T06:07:09.092Z'
updatedAt:
type: string
example: '2023-02-05T06:07:02.959Z'
organizationId:
type: string
example: 12345678-86af-4fba-afc6-c0cf87654321
tenantId:
type: string
example: 12345678-86af-4fba-afc6-c0cf87654321
scanId:
type: string
example: 12345678-86af-4fba-afc6-c0cf87654321
detectionID:
type: string
example: PLERION-AWS-1
detectionTitle:
type: string
example: >-
Ensure that IAM policies that allow full "*-*"
actions are not created
type:
type: string
example: helm
result:
type: string
example: FAILED
evaluatedKeys:
type: array
items:
type: string
example: aws_iam_policy_document
codeBlock:
type: array
items:
type: array
items:
- type: string
example: aws_iam_policy_document
- type: number
example: 1
file:
type: string
example: main.tf
repositoryPath:
type: string
example: >-
/repo/work/terraform-aws-eks/terraform-aws-eks/main.tf
lineRange:
type: array
items:
type: number
example: 1
resource:
type: string
example: aws_iam_policy_document
resourceTags:
type: object
example:
- key: Name
value: test
severityLevel:
type: string
example: CRITICAL
dashboardURL:
type: string
example: >-
https://au.api.plerion.com/shift-left/scans/0b58bd81-c66c-6fc5-72f4-10c070660219/finding/9a81ab1b-7120-4d47-84dd-4614aef50bee
meta:
type: object
properties:
page:
type: number
perPage:
type: number
total:
type: number
hasNextPage:
type: boolean
hasPreviousPage:
type: boolean
examples:
example-0:
summary: Found
description: Response when findings are found
value:
data:
- id: 3b79e265-090c-48e7-bbaa-fa96c4317530
createdAt: '2023-05-08T04:31:30.785Z'
updatedAt: '2023-05-08T04:31:30.785Z'
tenantId: 7934cf6d-fb34-4bda-adde-173a1fa30d9c
organizationId: ec17a309-6b0a-4911-8d1d-8a5aa0ac4742
scanId: 6ddde0c3-690a-aeb3-b237-9724b3e4403c
detectionId: PLERION-K8S-108
detectionTitle: >-
Ensure that the --allow-privileged argument is set to
false
type: helm
result: FAILED
evaluatedKeys: []
codeBlock:
- - 3
- |
apiVersion: apps/v1
- - 4
- |
kind: DaemonSet
- - 5
- |
metadata:
- - 6
- |2
name: release-prometheus-exporter
- - 7
- |2
namespace: default
- - 8
- |2
labels:
- - 9
- |2
app: prometheus-exporter
- - 10
- |2
heritage: Helm
- - 11
- |2
release: prometheus-exporter
- - 12
- |2
chart: prometheus-exporter-9.1.4
- - 13
- |2
jobLabel: prometheus-exporter
file: /prometheus-exporter/templates/daemonset.yaml
repositoryPath: /prometheus-exporter/templates/daemonset.yaml
lineRange:
- 3
- 94
resource: DaemonSet.default.release-name-prometheus-exporter
resourceTags: null
severityLevel: LOW
dashboardURL: >-
https://au.api.plerion.com/shift-left/scans/6ddde0c3-690a-aeb3-b237-9724b3e4403c/finding/3b79e265-090c-48e7-bbaa-fa96c4317530
meta:
page: 1
perPage: 10
total: 3225
hasNextPage: true
hasPreviousPage: false
example-1:
summary: Not Found
description: Response when findings are not found
value:
data: []
meta:
page: 1
perPage: 10
total: 0
hasNextPage: false
hasPreviousPage: false
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
example: >-
sortBy must be one of the following: id, createdAt,
updatedAt, artifactName, status
examples:
example-0:
summary: Invalid sortBy
description: Response when sortBy is invalid
value:
errors:
- message: >-
sortBy must be one of the following: id, detectionId,
type, result, file, severityLevel, 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}"
````