openapi: 3.2.0
info:
title: Picus Customer Threats API
description: '<p class="body-1">You can access the simulation raw data using the Rest API. Scope of the API includes; Simulation list, Simulation Details, Threat/Objective/Action Results, Results mapped to MITRE ATTC&K and Unified Kill Chain frameworks, Detection Analysis Results, Validated Logs & Alerts with SIEM & EDR integration.</p>
<p class="body-1">OAuth2 protocol is used to authorize Refresh/Access tokens. To obtain the API, you should generate a refresh token and then request an access token using the /v1/auth/token endpoint. The refresh token will be valid for 6 months, whereas the access token will be available for 2 hours. After getting the access token, add Authorization: Bearer {accessToken} to the header to request access to the below endpoints.</p>
<p class="body-1">Endpoints returning data with a lot of load works with the pagination method. You can use the offset and limit parameters to get the correct page.</p>
<i class="body-1">Your usage will be limited with your Picus license.</i>'
version: '1.0'
servers:
- url: https://api.picussecurity.com/
security:
- Access-Token: []
tags:
- name: Threats
paths:
/v1/threat-library/action-parameters:
get:
security:
- Access-Token: []
description: This endpoint returns all available parameters required to create an action. It provides the complete configuration schema, including supported fields, available option values, and related metadata necessary for action creation.
tags:
- Threats
summary: '# Action Parameters'
operationId: actionParametersParams
parameters:
- x-go-name: ModuleName
description: List Action Parameters with Module Name
name: module_name
in: query
schema:
type: string
responses:
'200':
$ref: '#/components/responses/ActionParametersResponse'
'422':
$ref: '#/components/responses/validationErrorSwagger'
default:
$ref: '#/components/responses/genericErrorSwagger'
servers:
- url: https://api.picussecurity.com/
/v1/threat-library/actions:
get:
security:
- Access-Token: []
description: Action Details; Action Id, Action Display Id, Action Name, Action Release Date, Action Description, Action Affected Os, Action Affected Products, Action Affected Platforms, Action Category, Attack Module, Mitres, Unified Kill Chains, Module Based Details, Owasp, Reference Links, Keyword Queries
tags:
- Threats
summary: '# Action Details List'
operationId: actionDetailsList
parameters:
- x-go-name: ActionIDs
description: List Action Details With Action ID List. (Max 100 ids)
name: action_ids
in: query
schema:
type: array
items:
type: integer
format: uint64
- x-go-name: ActionDisplayIDs
description: List Action Details With Action Display ID List. (Max 100 display ids)
name: action_display_ids
in: query
schema:
type: array
items:
type: integer
format: uint64
responses:
'200':
$ref: '#/components/responses/ActionDetailListReturnResponse'
default:
$ref: '#/components/responses/genericErrorSwagger'
servers:
- url: https://api.picussecurity.com/
post:
security:
- Access-Token: []
description: Creates custom actions with given arguments
tags:
- Threats
summary: '# CreateAction'
operationId: createActionParams
responses:
'200':
$ref: '#/components/responses/ActionCreateReturnResponse'
'422':
$ref: '#/components/responses/validationErrorSwagger'
default:
$ref: '#/components/responses/genericErrorSwagger'
servers:
- url: https://api.picussecurity.com/
requestBody:
content:
application/json:
schema:
type: object
properties:
action_result:
type: string
x-go-name: ActionResult
example: unblocked
affected_os:
type: array
items:
type: string
x-go-name: AffectedOs
example:
- Windows
affected_platform_ids:
type: array
items:
type: integer
format: int64
x-go-name: AffectedPlatformIds
example:
- 1
attack_module:
type: string
x-go-name: AttackModule
example: Endpoint Scenario
category:
type: string
x-go-name: Category
example: Attack Scenario
description:
type: string
x-go-name: Description
example: Stops the Defender service using sc.exe
is_privileged:
type: boolean
x-go-name: IsPrivileged
example: false
is_sensitive_content:
type: boolean
x-go-name: IsSensitiveContent
example: false
keyword:
type: string
x-go-name: Keyword
example: '"((\"process_name\" AND \"argument\") OR (\"log_source\")) AND NOT ((\"PICUS_REWIND\") OR (\"File created:\" AND (\"Scenarios\" OR \"Simulation\")))"'
name:
type: string
x-go-name: Name
example: Stop Windows Defender service
play_processes:
description: 'in: body'
type: array
items:
$ref: '#/components/schemas/ProcessActionParams'
x-go-name: PlayProcesses
process_result:
type: string
x-go-name: ProcessResult
example: P1
remote_file_ids:
description: Remote file ids (from the file upload endpoint) to attach to the action
type: array
items:
type: integer
format: uint64
x-go-name: RemoteFileIds
example:
- 1000001
rewind_processes:
description: 'in: body'
type: array
items:
$ref: '#/components/schemas/ProcessActionParams'
x-go-name: RewindProcesses
sources:
type: array
items:
type: string
x-go-name: Sources
example:
- EDR
tactic_id:
type: integer
format: int64
x-go-name: TacticId
example: 6
tags:
type: array
items:
type: string
x-go-name: Tags
example:
- APT 10
technique_id:
type: integer
format: int64
x-go-name: TechniqueId
example: 25
title:
description: 'in: body'
type: string
x-go-name: Title
ukc_phase_id:
type: integer
format: int64
x-go-name: UkcPhaseId
example: 7
url:
description: 'in: body'
type: string
x-go-name: Url
url_category:
type: string
x-go-name: UrlCategory
example: Ads
use_case:
type: string
x-go-name: UseCase
example: Sensitive Data Exposure
/v1/threat-library/actions/custom-keyword:
post:
security:
- Access-Token: []
description: 'Generates the detection keyword (query) for a custom action based on the given attack module
and its related fields (file hashes, file name, play process ids, url or action id).
The returned keyword can then be passed to the Create Action endpoint.'
tags:
- Threats
summary: '# Custom Action Keyword'
operationId: customActionKeywordParams
responses:
'200':
$ref: '#/components/responses/CustomActionKeywordReturnResponse'
'422':
$ref: '#/components/responses/validationErrorSwagger'
default:
$ref: '#/components/responses/genericErrorSwagger'
servers:
- url: https://api.picussecurity.com/
requestBody:
content:
application/json:
schema:
type: object
properties:
action_id:
description: Action id (data exfiltration / email modules)
type: integer
format: uint64
x-go-name: ActionID
file_name:
description: File name (file-based modules)
type: string
x-go-name: FileName
md5:
description: MD5 hash of the file
type: string
x-go-name: MD5
module:
description: Attack module the action belongs to
type: string
x-go-name: Module
play_process:
description: Play process ids (endpoint modules)
type: array
items:
type: integer
format: uint64
x-go-name: PlayProcess
sha1:
description: SHA1 hash of the file
type: string
x-go-name: SHA1
sha256:
description: SHA256 hash of the file
type: string
x-go-name: SHA256
url:
description: URL (URL Filtering module)
type: string
x-go-name: URL
/v1/threat-library/actions/{ActionId}:
get:
security:
- Access-Token: []
description: Action Details; Action Id, Action Display Id, Action Name, Action Release Date, Action Description, Action Affected Os, Action Affected Products, Action Affected Platforms, Action Category, Attack Module, Mitres, Unified Kill Chains, Module Based Details, Owasp, Reference Links, Keyword Queries
tags:
- Threats
summary: '# Action Details'
operationId: actionDetails
parameters:
- description: Action ID (URI parameter)
name: ActionId
in: path
required: true
schema:
type: integer
format: uint64
responses:
'200':
$ref: '#/components/responses/ActionDetailReturnResponse'
default:
$ref: '#/components/responses/genericErrorSwagger'
servers:
- url: https://api.picussecurity.com/
/v1/threat-library/files:
get:
security:
- Access-Token: []
description: 'Files List;
Default limit: 100, Default offset: 0
Max limit: 100'
tags:
- Threats
summary: '# Files List'
operationId: filesListParams
parameters:
- x-go-name: Limit
name: limit
in: query
schema:
type: integer
format: int64
- x-go-name: Offset
name: offset
in: query
schema:
type: integer
format: int64
- x-go-name: Type
description: File Type can be local or remote
name: type
in: query
schema:
type: string
- x-go-name: NameLike
description: name like can be someFileName
name: nameLike
in: query
schema:
type: string
responses:
'200':
$ref: '#/components/responses/FileListReturnResponse'
'422':
$ref: '#/components/responses/validationErrorSwagger'
default:
$ref: '#/components/responses/genericErrorSwagger'
servers:
- url: https://api.picussecurity.com/
post:
security:
- Access-Token: []
description: 'Uploads a file that can later be referenced when creating custom actions or processes.
The file must be sent as multipart/form-data under the "file" field.'
tags:
- Threats
summary: '# Upload File'
operationId: fileUploadParams
responses:
'200':
$ref: '#/components/responses/FileUploadReturnResponse'
'422':
$ref: '#/components/responses/validationErrorSwagger'
default:
$ref: '#/components/responses/genericErrorSwagger'
servers:
- url: https://api.picussecurity.com/
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
description: The file to upload, sent as multipart/form-data under the "file" field
format: binary
file_type:
type: string
description: File type (e.g. exe, dll, log). If empty it is derived from the file name.
type:
type: string
description: 'Whether the file is stored locally or referenced remotely: local or remote'
download_path:
type: string
description: Download path, used when the file is referenced remotely
is_executable:
type: boolean
description: Whether the uploaded file is executable
skip_zip_extract:
type: boolean
description: Whether to skip extracting the uploaded zip archive
/v1/threat-library/processes:
get:
security:
- Access-Token: []
description: 'Processes;
Default limit: 100, Default offset: 0
Max limit: 100'
tags:
- Threats
summary: '# Process List'
operationId: processListParams
parameters:
- x-go-name: Limit
name: limit
in: query
schema:
type: integer
format: int64
- x-go-name: Offset
name: offset
in: query
schema:
type: integer
format: int64
- x-go-name: ProcessType
description: List Process With Process Type
name: process_type
in: query
schema:
type: string
responses:
'200':
$ref: '#/components/responses/ProcessListReturnResponse'
'422':
$ref: '#/components/responses/validationErrorSwagger'
default:
$ref: '#/components/responses/genericErrorSwagger'
servers:
- url: https://api.picussecurity.com/
post:
security:
- Access-Token: []
description: Creates custom processes with given arguments
tags:
- Threats
summary: '# Create Process'
operationId: createProcessParams
responses:
'200':
$ref: '#/components/responses/ProcessCreateReturnResponse'
'422':
$ref: '#/components/responses/validationErrorSwagger'
default:
$ref: '#/components/responses/genericErrorSwagger'
servers:
- url: https://api.picussecurity.com/
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProcessListInput'
/v1/threat-library/tags:
get:
security:
- Access-Token: []
description: List tags for threats
tags:
- Threats
summary: '# List Tags'
operationId: Tags
responses:
'200':
$ref: '#/components/responses/TagsListReturnResponse'
'422':
$ref: '#/components/responses/validationErrorSwagger'
default:
$ref: '#/components/responses/genericErrorSwagger'
servers:
- url: https://api.picussecurity.com/
/v1/threat-library/threat-actors:
get:
security:
- Access-Token: []
description: List threat actors
tags:
- Threats
summary: '# List Threat Actors'
operationId: Threat-Actors
responses:
'200':
$ref: '#/components/responses/ThreatActorListReturnResponse'
'422':
$ref: '#/components/responses/validationErrorSwagger'
default:
$ref: '#/components/responses/genericErrorSwagger'
servers:
- url: https://api.picussecurity.com/
/v1/threat-library/threats:
get:
security:
- Access-Token: []
description: Threat List; Threat ID, Threat Display ID, Threat Name, Release Date, Severity, Tags, Affected Operating Systems, Is Predefined, Attack Categories, Attack Module Ids, Unified Kill Chain Phases, Mitres
tags:
- Threats
summary: '# Threat List'
operationId: threatListParams
parameters:
- x-go-name: Limit
name: limit
in: query
schema:
type: integer
format: int64
- x-go-name: Offset
name: offset
in: query
schema:
type: integer
format: int64
- x-go-name: Severities
description: 'Filter with Severity (one or more severity): Low | Medium | High'
name: severities
in: query
schema:
type: array
items:
type: string
- x-go-name: AttackCategoryIds
description: 'Filter with one or more Attack Category IDs.
Available attack categories, as `id: name (attack module)`:
1: Malicious Code (Network Infiltration)
2: Attack Scenario (Windows Endpoint Scenario)
3: Vulnerability Exploitation (Network Infiltration)
4: Web Application (Web Application)
5: Malicious Code (E-mail Infiltration)
6: Vulnerability Exploitation (E-mail Infiltration)
7: Data Exfiltration (Data Exfiltration)
37: Attack Scenario (Linux Endpoint Scenario)
38: Attack Scenario (macOS Endpoint Scenario)
39: Lateral Movement Techniques (Windows Endpoint Scenario)
41: URL Filtering (URL Filtering)
42: Attack Scenario (Kubernetes Endpoint Scenario)
137: Azure ARM (Azure Cloud Emulation)
138: Azure Entra ID (Azure Cloud Emulation)
139: Azure m365 (Azure Cloud Emulation)
140: AWS (AWS Cloud Emulation)
141: GCP (GCP Cloud Emulation)'
name: attack_category_ids
in: query
schema:
type: array
items:
type: integer
format: int64
- x-go-name: AttackModuleIds
description: 'Filter with one or more Attack Module IDs.
Available attack modules, as `id: name`:
1: Network Infiltration
2: Windows Endpoint Scenario
3: Web Application
4: E-mail Infiltration
5: Data Exfiltration
6: Linux Endpoint Scenario
7: macOS Endpoint Scenario
9: URL Filtering
10: Kubernetes Endpoint Scenario
103: Azure Cloud Emulation
104: AWS Cloud Emulation
105: GCP Cloud Emulation'
name: attack_module_ids
in: query
schema:
type: array
items:
type: integer
format: int64
- x-go-name: ReleaseDateGte
description: Filter with Release Date Greater Than or Equals.
name: release_date_gte
in: query
schema:
type: integer
format: int64
- x-go-name: ReleaseDateLte
description: Filter with Release Date Less Than or Equals.
name: release_date_lte
in: query
schema:
type: integer
format: int64
- x-go-name: IsPredefined
description: Filter with whether threat is predefined.
name: is_predefined
in: query
schema:
type: boolean
- x-go-name: AffectedProducts
description: Filter with Affected Products.
name: affected_products
in: query
schema:
type: array
items:
type: string
- x-go-name: AffectedOS
description: Filter with Affected Operating Systems. Windows | Linux | macOS
name: affected_os
in: query
schema:
type: array
items:
type: string
- x-go-name: UnifiedKillChains
description: Filter with Unified Kill Chain Phases.
name: unified_kill_chains
in: query
schema:
type: array
items:
type: string
- x-go-name: ThreatActors
description: Threat Actors Filter
name: threat_actors
in: query
schema:
type: array
items:
type: string
- x-go-name: MitreAttack
description: Mitre Tactics Filter
name: mitre_attack
in: query
schema:
type: array
items:
type: string
- x-go-name: AttackerObjectives
description: Attacker Objectives Filter
name: attacker_objectives
in: query
schema:
type: array
items:
type: string
responses:
'200':
$ref: '#/components/responses/ThreatsReturnResponse'
default:
$ref: '#/components/responses/genericErrorSwagger'
servers:
- url: https://api.picussecurity.com/
post:
security:
- Access-Token: []
description: Creates custom threats with given arguments
tags:
- Threats
summary: '# Create Threat'
operationId: createThreatParams
responses:
'200':
$ref: '#/components/responses/ThreatCreateReturnResponse'
'422':
$ref: '#/components/responses/validationErrorSwagger'
default:
$ref: '#/components/responses/genericErrorSwagger'
servers:
- url: https://api.picussecurity.com/
requestBody:
content:
application/json:
schema:
type: object
required:
- name
- objectives
- result_condition
properties:
affected_os:
description: 'Affected OS
[Windows]'
type: array
items:
type: string
x-go-name: AffectedOS
example:
- Windows
description:
description: Description
type: string
x-go-name: Description
example: Simulates disabling the built-in Windows Defender service.
from_campaign:
description: from threat id
type: integer
format: uint64
x-go-name: FromCampaign
example: 0
name:
description: Name
type: string
x-go-name: Name
example: Disable Windows Defender
objectives:
description: Objectives
type: array
items:
$ref: '#/components/schemas/CustomCampaignObjectiveParams'
x-go-name: Objectives
example:
- action_ids:
- 1000123
name: A1
result_condition: unblocked
result_condition:
description: 'Result condition
type: string'
type: string
x-go-name: ResultCondition
example: A1
severity:
description: 'Threat severity level
options: `High`, `Medium` and `Low`'
type: string
x-go-name: Severity
example: High
tags:
description: Tags
type: array
items:
type: string
x-go-name: Tags
example:
- APT 10
- Evasion
threat_actor_id:
$ref: '#/components/schemas/NullInt64'
/v1/threat-library/threats/import:
post:
security:
- Access-Token: []
description: 'Imports a threat pack from a YAML file or an encrypted zip archive containing
a YAML definition and optional payload files. Returns the created threat details.
For detailed information on how to construct the threat file, please refer to the guide
at https://support.picussecurity.com/hc/en-us/articles/36765648951837.'
tags:
- Threats
summary: '# Import Threat Pack'
operationId: importThreatParams
responses:
'200':
$ref: '#/components/responses/ImportThreatPackReturnResponse'
'422':
$ref: '#/components/responses/validationErrorSwagger'
default:
$ref: '#/components/responses/genericErrorSwagger'
servers:
- url: https://api.picussecurity.com/
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
description: The threat pack file to import (.yaml, .yml, or encrypted .zip)
format: binary
/v1/threat-library/threats/{ThreatId}:
get:
security:
- Access-Token: []
description: Threat Details; Threat ID, Threat Display ID, Threat Name, Release Date, Severity, Tags, Affected Operating Systems, Is Predefined, Attack Categories, Attack Module Ids, Unified Kill Chain Phases, Mitres, Threat Description, Affected Products, Action Category Id, Applicable Agent Types, Objective Flows, Threat Actors
tags:
- Threats
summary: '# Threat Details'
operationId: threatDetails
parameters:
- description: Threat ID (URI parameter)
name: ThreatId
in: path
required: true
schema:
type: integer
format: uint64
responses:
'200':
$ref: '#/components/responses/ThreatDetailReturnResponse'
default:
$ref: '#/components/responses/genericErrorSwagger'
servers:
- url: https://api.picussecurity.com/
put:
security:
- Access-Token: []
description: Updates custom threats with given arguments
tags:
- Threats
summary: '# Update Threat'
operationId: updateThreatParams
parameters:
- description: Threat ID (URI parameter)
name: ThreatId
in: path
required: true
schema:
type: integer
format: uint64
responses:
'200':
$ref: '#/components/responses/ThreatUpdateReturnResponse'
'422':
$ref: '#/components/responses/validationErrorSwagger'
default:
$ref: '#/components/responses/genericErrorSwagger'
servers:
- url: https://api.picussecurity.com/
requestBody:
content:
application/json:
schema:
type: object
properties:
affected_os:
description: 'Affected OS
[Windows]'
type: array
items:
type: string
x-go-name: AffectedOS
example:
- Windows
description:
description: Description
type: string
x-go-name: Description
example: Updated simulation for disabling Windows Defender service.
from_campaign:
description: from threat id
type: integer
format: uint64
x-go-name: FromCampaign
example: 0
name:
description: Name
type: string
x-go-name: Name
example: Updated Windows Defender Disable
objectives:
description: Objectives
type: array
items:
$ref: '#/components/schemas/CustomCampaignObjectiveParams'
x-go-name: Objectives
example:
- action_ids:
- 1000123
name: A1
result_condition: unblocked
result_condition:
description: 'Result condition
type: string'
type: string
x-go-name: ResultCondition
example: A1
severity:
description: 'Threat severity level
options: `High`, `Medium` and `Low`'
type: string
x-go-name: Severity
example: High
tags:
description: Tags
type: array
items:
type: string
x-go-name: Tags
example:
- APT 10
- Evasion
- Updated
threat_actor_id:
$ref: '#/components/schemas/NullInt64'
delete:
security:
- Access-Token: []
description: Deletes custom threats with given threat ID
tags:
- Threats
summary: '# Delete Threat'
operationId: deleteThreatParams
parameters:
- description: Threat ID (URI parameter)
name: ThreatId
in: path
required: true
schema:
type: integer
format: uint64
responses:
'200':
$ref: '#/components/responses/ThreatDeleteReturnResponse'
'422':
$ref: '#/components/responses/validationErrorSwagger'
default:
$ref: '#/components/responses/genericErrorSwagger'
servers:
- url: https://api.picussecurity.com/
/v1/threat-library/threats/{ThreatId}/export:
get:
security:
- Access-Token: []
description: 'Exports a custom threat as an encrypted zip file containing the threat definition
and any associated files. The response is a binary file download.'
tags:
- Threats
summary: '# Export Threat Pack'
operationId: exportThreatParams
parameters:
- description: Threat ID (URI parameter)
name: ThreatId
in: path
required: true
schema:
type: integer
format: uint64
responses:
'200':
$ref: '#/components/responses/fileResponse'
'422':
$ref: '#/components/responses/validationErrorSwagger'
default:
$ref: '#/components/responses/genericErrorSwagger'
servers:
- url: https://api.picussecurity.com/
/v2/threat-library/actions:
get:
security:
- Access-Token: []
description: 'Action List; Action Id, Action Display Id, Updated At, Action Name
Default limit: 100, Default offset: 0
Max limit: 100'
tags:
- Threats
summary: '# Action List'
operationId: actionListParams
parameters:
- x-go-name: Limit
name: limit
in: query
schema:
type: integer
format: int64
- x-go-name: Offset
name: offset
in: query
schema:
type: integer
format: int64
- x-go-name: UpdatedAtGte
description: List Actions With Updated At Greater Than or Equal to UpdatedAtGte.
name: updated_at_gte
in: query
schema:
typ
# --- truncated at 32 KB (73 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/picus-security/refs/heads/main/openapi/picus-security-threats-api-openapi.yml