generated: '2026-08-02'
method: derived
source: >-
  Derived from openapi/_original/picus-security-openapi.json (Swagger 2.0; 71 paths, 84 operations,
  141 definitions, 83 shared responses): schema $ref links between definitions and id-reference fields
  (agent_id, template_id, integration_id, action_id, node_id, content_id, role_id, exposure_id, asset_id,
  cve_id, technique_id, tactic_id, sub_technique_id), cross-checked against the path grammar.
docs: https://apidocs.picussecurity.com/reference/intro-to-the-picus-customer-api
notation: >-
  Relationships are written from the entity that owns the reference field, using has_one / has_many /
  belongs_to with the JSON field name in `via`. Ids are integers unless noted. There is no URN scheme;
  entities are addressed by integer id in the path (e.g. /v1/simulations/{Id}/run/{RunId}).
id_grammar:
  style: integer-path-ids
  path_params: [Id, RunId, ThreatId, ActionId, IntegrationId, DeviceId, ReportId, PeerId, SimulationId, content_id, source, ruleId, userId]
  dual_identifier_note: >-
    Actions carry BOTH an internal `action_id` and a customer-facing `action_display_id` / `display_id`.
    Repeated actions inside one threat are disambiguated by `node_id` — several result endpoints accept
    `node_id` as an optional query parameter and default to the first node when it is omitted.
domains:
- name: "simulation"
  description: "Simulations, their scheduled runs, and run results"
- name: "threat_library"
  description: "Threats, actions, processes, files, tags and threat actors"
- name: "template"
  description: "Reusable static/dynamic simulation templates"
- name: "agent"
  description: "Picus agents (peers) that execute simulations"
- name: "integration"
  description: "SIEM/EDR integrations and their collector agents"
- name: "mitigation"
  description: "Mitigation devices, signatures and detection content"
- name: "framework"
  description: "MITRE ATT&CK and Unified Kill Chain classification vocabularies"
- name: "exposure"
  description: "Host/exposure instance scoring"
- name: "identity"
  description: "Users, roles and activity logs"
- name: "reporting"
  description: "Generated simulation result reports"

entities:
- name: "Simulation"
  schema: "SimulationApiOutput"
  list_schema: "SimulationSummary"
  detail_schema: "SimulationDetailsReturn"
  domain: "simulation"
  path: "/v1/simulations/{Id}"
  description: "A configured security validation run — a template plus an agent plus a schedule."
- name: "SimulationRun"
  schema: "SimulationRunApiOutput"
  alt_schema: "SimulationRunReturn"
  domain: "simulation"
  path: "/v1/simulations/{Id}/run/{RunId}"
  description: "One execution of a simulation, carrying prevention and detection results."
- name: "SimulationResult"
  schema: "SimulationResultDTO"
  domain: "simulation"
  description: "The scored outcome of a run — prevention (blocked/not blocked) and detection (logged/alerted) summaries."
- name: "SimulationRunThreat"
  schema: "SimulationRunThreat"
  domain: "simulation"
  description: "One threat as executed inside a run, with its objectives and action results."
- name: "Threat"
  schema: "ThreatReturn"
  list_schema: "ThreatsReturn"
  domain: "threat_library"
  path: "/v1/threat-library/threats/{ThreatId}"
  description: "An adversary scenario composed of objectives and actions; can be custom-authored, imported and exported as a threat pack."
- name: "Objective"
  schema: "Objective"
  domain: "threat_library"
  description: "An attacker objective inside a threat; modelled as a flow of nodes."
- name: "FlowNode"
  schema: "FlowNode"
  domain: "threat_library"
  description: "A node in an objective flow with true_items/false_items branches — a self-referential tree."
- name: "Action"
  schema: "ActionReturn"
  detail_schema: "ActionDetailsDTO"
  summary_schema: "ActionSummary"
  domain: "threat_library"
  path: "/v1/threat-library/actions/{ActionId}"
  description: "A single atomic attack technique executed by an agent."
- name: "AttackModule"
  schema: "AttackModule"
  domain: "threat_library"
  description: "The execution module an action belongs to (e.g. endpoint, network, email, web application)."
- name: "AttackCategory"
  schema: "AttackCategory"
  domain: "threat_library"
  description: "Category classification applied to threats and actions."
- name: "Process"
  schema: "Process"
  domain: "threat_library"
  path: "/v1/threat-library/processes"
  description: "A custom process definition usable inside custom actions."
- name: "File"
  schema: "File"
  alt_schema: "FileApiOutput"
  domain: "threat_library"
  path: "/v1/threat-library/files"
  description: "An uploaded payload file referenced by custom actions and processes."
- name: "ThreatActor"
  schema: "ThreatActor"
  domain: "threat_library"
  path: "/v1/threat-library/threat-actors"
  description: "A named adversary group associated with threats."
- name: "Template"
  schema: "TemplateReturn"
  detail_schema: "TemplateDetailReturn"
  domain: "template"
  path: "/v1/templates/{Id}"
  description: "A reusable set of threats plus rules that a simulation instantiates."
- name: "TemplateRule"
  schema: "TemplateRule"
  alt_schema: "RulesReturn"
  domain: "template"
  description: "A selection rule on a dynamic template (which threats to include)."
- name: "Agent"
  schema: "AgentReturn"
  detail_schema: "AgentDetailReturn"
  summary_schema: "AgentSummary"
  domain: "agent"
  path: "/v1/agents/{Id}"
  description: "A deployed Picus agent (windows/linux/macos/kubernetes) that executes simulations."
- name: "AgentType"
  schema: "AgentType"
  domain: "agent"
  description: "Agent platform/variant vocabulary used by download-link, install-token and reinstall-token."
- name: "Integration"
  schema: "IntegrationSummary"
  domain: "integration"
  path: "/v1/integrations"
  description: "A configured SIEM/EDR integration used to collect logs and alerts as detection evidence."
- name: "IntegrationAgent"
  schema: "IntegrationAgent"
  domain: "integration"
  path: "/v1/integrations/agents"
  description: "The collector agent that services an integration."
- name: "MitigationDevice"
  schema: "MitigationDeviceCustomerApiResponse"
  alt_schema: "Device"
  domain: "mitigation"
  path: "/v2/mitigation/devices/{DeviceId}"
  description: "A prevention device (firewall/IPS/WAF) whose blocked/not-blocked counts are scored."
- name: "Signature"
  schema: "Signature"
  domain: "mitigation"
  path: "/v1/mitigation/devices/{DeviceId}/signatures"
  description: "A vendor-specific prevention signature recommended for a device."
- name: "DetectionContentSource"
  schema: "SourceWithRuleCount"
  alt_schema: "ContentSourceItem"
  domain: "mitigation"
  path: "/v1/mitigation/detection-content/sources"
  description: "A detection content source (e.g. Splunk, QRadar, CrowdStrike)."
- name: "LogSource"
  schema: "LogSourceDTO"
  alt_schema: "DetectionContentLogSourceCustomerApiResponse"
  domain: "mitigation"
  description: "A log source belonging to a detection content source."
- name: "DetectionRule"
  schema: "RuleDTO"
  detail_schema: "DetectionContentRuleDetailCustomerApiResponse"
  domain: "mitigation"
  path: "/v1/mitigation/detection-content/{source}/rules/{ruleId}"
  description: "A vendor detection rule mapped to actions and MITRE techniques."
- name: "CustomDetectionContent"
  schema: "CustomRuleDTO"
  input_schema: "CustomDetectionContentParams"
  domain: "mitigation"
  path: "/v1/mitigation/detection-content/custom/{content_id}"
  description: "Customer-authored detection content built from actions plus MITRE technique selections."
- name: "MitreTactic"
  schema: "TacticResults"
  domain: "framework"
  path: "/v1/mitigation/detection-content/mitre/tactics"
  description: "A MITRE ATT&CK tactic."
- name: "MitreTechnique"
  schema: "Technique"
  alt_schema: "TechniqueInfoDTO"
  domain: "framework"
  path: "/v1/mitigation/detection-content/mitre/techniques"
  description: "A MITRE ATT&CK technique."
- name: "MitreSubTechnique"
  schema: "SubTechnique"
  domain: "framework"
  path: "/v1/mitigation/detection-content/mitre/sub-techniques"
  description: "A MITRE ATT&CK sub-technique, carrying its parent technique reference."
- name: "UnifiedKillChain"
  schema: "Ukc"
  alt_schema: "UkcDTO"
  domain: "framework"
  description: "Unified Kill Chain phase/stage classification returned on run results."
- name: "ExposureInstanceScore"
  schema: "ScoreItem"
  input_schema: "HostExposurePairSwagger"
  domain: "exposure"
  path: "/v1/exposures/instances/scores"
  description: "The exposure score for one host+exposure (asset_id + cve_id) pair."
- name: "User"
  schema: "User"
  domain: "identity"
  path: "/v1/users/{userId}"
  description: "A Picus platform user with an assigned role."
- name: "Role"
  schema: "Role"
  domain: "identity"
  path: "/v1/users/roles"
  description: "A role granting a permission set; assigned via PUT /v1/users/{userId}/role."
- name: "ActivityLog"
  schema: "ActivityLog"
  domain: "identity"
  path: "/v1/activity-logs"
  description: "An audit record of platform activity, filterable by date range."
- name: "SimulationReport"
  schema: "SimulationReportBasicOutput"
  input_schema: "GenerateSimulationReportInput"
  domain: "reporting"
  path: "/v2/simulations/{Id}/results/reports/{ReportId}"
  description: "A generated report over a simulation overview or a specific run."

relationships:
# simulation graph
- from: "Simulation"
  to: "Agent"
  kind: "has_one"
  via: "agent_id"
  note: "SimulationApiOutput.agent_id (NullInt64); SimulationDetailsReturn.agent is an AgentSummary"
- from: "Simulation"
  to: "Template"
  kind: "has_one"
  via: "template_id"
  note: "SimulationApiOutput.template_id (NullInt64)"
- from: "Simulation"
  to: "SimulationRun"
  kind: "has_many"
  via: "simulation_run"
  note: "SimulationDetailsReturn.simulation_run"
- from: "Simulation"
  to: "AssessmentProtocol"
  kind: "has_many"
  via: "protocols"
- from: "Simulation"
  to: "StatusDetails"
  kind: "has_one"
  via: "status_details"
- from: "Simulation"
  to: "Detection"
  kind: "has_one"
  via: "detection_analysis"
- from: "SimulationRun"
  to: "SimulationRunThreat"
  kind: "has_many"
  via: "threats"
  note: "exposed as GET /v1/simulations/{Id}/run/{RunId}/threats"
- from: "SimulationRun"
  to: "PreventionSummary"
  kind: "has_one"
  via: "prevention"
- from: "SimulationRun"
  to: "DetectionSummary"
  kind: "has_one"
  via: "detection"
- from: "SimulationRun"
  to: "Frameworks"
  kind: "has_one"
  via: "frameworks"
  note: "exposed as .../run/{RunId}/frameworks"
- from: "SimulationRunThreat"
  to: "Threat"
  kind: "belongs_to"
  via: "threat_id"
- from: "SimulationRunThreat"
  to: "Action"
  kind: "has_many"
  via: "actions"
  note: "exposed as .../threats/{ThreatId}/actions"
- from: "SimulationRun"
  to: "SimulationReport"
  kind: "has_many"
  via: "reports"
  note: "POST /v2/simulations/{Id}/results/reports"
# result evidence graph
- from: "ActionDetailsDTO"
  to: "DetectionResult"
  kind: "has_one"
  via: "detection_analysis"
- from: "ActionDetailsDTO"
  to: "Frameworks"
  kind: "has_one"
  via: "frameworks"
- from: "ActionDetailsDTO"
  to: "ModuleBasedResults"
  kind: "has_one"
  via: "module_based_results"
- from: "ActionDetailsDTO"
  to: "ProtocolBasedResults"
  kind: "has_many"
  via: "protocol_based_result"
- from: "ActionDetailsDTO"
  to: "PlatformCommon"
  kind: "has_many"
  via: "affected_platforms"
- from: "ActionDetailsDTO"
  to: "ActionDetailReferences"
  kind: "has_one"
  via: "references"
- from: "ActionDetailReferences"
  to: "Reference"
  kind: "has_one"
  via: "cve_reference"
- from: "ActionDetailReferences"
  to: "Reference"
  kind: "has_one"
  via: "cwe_reference"
- from: "ActionDetailReferences"
  to: "Reference"
  kind: "has_many"
  via: "virus_total_reference"
- from: "IntegrationBasedResult"
  to: "Integration"
  kind: "belongs_to"
  via: "integration_id"
- from: "IntegrationBasedResult"
  to: "Alert"
  kind: "has_one"
  via: "alert"
- from: "IntegrationBasedResult"
  to: "Logging"
  kind: "has_one"
  via: "log"
- from: "SimulationResultsDetectionDTO"
  to: "RunIntegration"
  kind: "has_many"
  via: "integrations"
- from: "ModuleBasedResults"
  to: "ActionDetailProcess"
  kind: "has_many"
  via: "process_results"
- from: "ModuleBasedResults"
  to: "FileDetailsCommon"
  kind: "has_many"
  via: "file_details"
# threat library graph
- from: "Threat"
  to: "Objective"
  kind: "has_many"
  via: "flows"
- from: "Threat"
  to: "AttackModule"
  kind: "has_many"
  via: "attack_modules"
- from: "Threat"
  to: "AttackCategory"
  kind: "has_many"
  via: "attack_categories"
- from: "Threat"
  to: "MitreTechnique"
  kind: "has_many"
  via: "mitre_attack"
  note: "MitreDTO"
- from: "Threat"
  to: "UnifiedKillChain"
  kind: "has_many"
  via: "unified_kill_chains"
  note: "UkcDTO"
- from: "Objective"
  to: "FlowNode"
  kind: "has_many"
  via: "nodes"
- from: "FlowNode"
  to: "FlowNode"
  kind: "has_many"
  via: "true_items"
  note: "self-referential branch"
- from: "FlowNode"
  to: "FlowNode"
  kind: "has_many"
  via: "false_items"
  note: "self-referential branch"
- from: "FlowNode"
  to: "Action"
  kind: "belongs_to"
  via: "display_id"
- from: "Action"
  to: "AttackModule"
  kind: "belongs_to"
  via: "attack_module_id"
- from: "Action"
  to: "ModuleBasedDetails"
  kind: "has_one"
  via: "module_based_details"
- from: "Action"
  to: "Platform"
  kind: "has_many"
  via: "affected_platforms"
- from: "Action"
  to: "KWDictionary"
  kind: "has_many"
  via: "keyword_queries"
- from: "ModuleBasedDetails"
  to: "File"
  kind: "has_one"
  via: "file"
- from: "ModuleBasedDetails"
  to: "Process"
  kind: "has_many"
  via: "processes"
- from: "Process"
  to: "AffectedAction"
  kind: "has_many"
  via: "affected_actions"
- from: "Process"
  to: "ProcessFilesSummary"
  kind: "has_many"
  via: "process_files_summary"
- from: "Process"
  to: "File"
  kind: "has_many"
  via: "file_ids"
  note: "CreateProcessListInput.file_ids"
# template graph
- from: "Template"
  to: "Threat"
  kind: "has_many"
  via: "threats"
  note: "TemplateDetailReturn.threats (CampaignDetails)"
- from: "Template"
  to: "TemplateRule"
  kind: "has_many"
  via: "rules"
- from: "Template"
  to: "AgentType"
  kind: "has_many"
  via: "agent_types"
# agent + integration graph
- from: "Agent"
  to: "MitigationDevice"
  kind: "has_many"
  via: "devices"
- from: "Agent"
  to: "AttackModule"
  kind: "has_many"
  via: "attack_modules"
  note: "Module"
- from: "Agent"
  to: "AffectedPlatform"
  kind: "has_many"
  via: "affected_platforms"
- from: "Integration"
  to: "IntegrationAgent"
  kind: "has_one"
  via: "integration_agent_id"
# mitigation + detection content graph
- from: "MitigationDevice"
  to: "Signature"
  kind: "has_many"
  via: "signatures"
  note: "GET /v1/mitigation/devices/{DeviceId}/signatures"
- from: "DetectionContentSource"
  to: "LogSource"
  kind: "has_many"
  via: "log_sources"
- from: "DetectionContentSource"
  to: "DetectionRule"
  kind: "has_many"
  via: "rules"
- from: "DetectionRule"
  to: "Action"
  kind: "has_many"
  via: "actions"
  note: "IdNameInfoDTO / ActionWithCategoryDTO"
- from: "DetectionRule"
  to: "MitreTechnique"
  kind: "has_many"
  via: "mitre"
  note: "TechniqueInfoDTO"
- from: "CustomDetectionContent"
  to: "Action"
  kind: "has_many"
  via: "action_ids"
- from: "CustomDetectionContent"
  to: "MitreTechnique"
  kind: "has_many"
  via: "techniques"
- from: "CustomDetectionContent"
  to: "DetectionContentSource"
  kind: "has_many"
  via: "content_sources"
- from: "NotBlockedActionResponse"
  to: "Action"
  kind: "belongs_to"
  via: "action_id"
- from: "NotBlockedActionResponse"
  to: "SimulationRun"
  kind: "belongs_to"
  via: "assessment_run_id"
# framework graph
- from: "Frameworks"
  to: "MitreTactic"
  kind: "has_one"
  via: "mitre"
  note: "Mitre carries tactic_id / technique_id / sub_technique_id"
- from: "Frameworks"
  to: "UnifiedKillChain"
  kind: "has_one"
  via: "ukc"
- from: "MitreSubTechnique"
  to: "MitreTechnique"
  kind: "belongs_to"
  via: "technique_id"
- from: "MitreTechnique"
  to: "MitreTactic"
  kind: "belongs_to"
  via: "tactic_id"
# exposure + identity
- from: "ExposureInstanceScore"
  to: "Asset"
  kind: "belongs_to"
  via: "asset_id"
  note: "asset is not modelled as its own returnable entity in this contract"
- from: "ExposureInstanceScore"
  to: "CVE"
  kind: "belongs_to"
  via: "cve_id"
  note: "external identifier, not a Picus entity"
- from: "User"
  to: "Role"
  kind: "has_one"
  via: "role_id"
- from: "ActivityLog"
  to: "User"
  kind: "belongs_to"
  via: "user"

shared_shapes:
- name: "Pagination"
  schemas: "[Pagination, PaginationDTO]"
  note: "Offset/limit pagination envelope reused across list responses; see conventions/picus-security-conventions.yml"
- name: "OccurenceRate"
  note: "Counted outcome pair (achieved/notAchieved, logged/notLogged, alerted/notAlerted) reused across all summary schemas"
- name: "NullInt64 / NullBool / Int64Array / StringArray"
  note: "Go sql-null and array wrappers leaked into the public contract from the server implementation"
- name: "GenericIDNameItemDTO"
  note: "Generic {id,name} projection used for lookups"

notes:
- >-
  The core spine is Template -> Simulation -> SimulationRun -> SimulationRunThreat -> Action, with every run
  result carrying dual scoring (prevention: blocked/not-blocked; detection: logged/alerted) and dual framework
  mapping (MITRE ATT&CK + Unified Kill Chain).
- >-
  The contract exposes Go implementation types (NullInt64, NullBool, x-go-name on nearly every property),
  which is a design leak worth flagging to the provider — it constrains future re-implementation.
- >-
  No Asset entity is returnable: exposure instance scores accept asset_id/cve_id pairs as INPUT only
  (POST /v1/exposures/instances/scores) and omit unmatched pairs from the response.