Creates a Gray-Box, Red-Team, or Black-Box simulation. GRAY_BOX/BLACK_BOX are agent-based
(agent_id required; initial_machine additionally required for GRAY_BOX) and can be launched
instantly or on a schedule. RED_TEAM is stager-based (stager_id required instead of agent_id)
and only launches instantly - initial_machine and schedule are both rejected if sent.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
About
Create Simulation endpoint creates an Attack Path Validation simulation and returns the UUID of the created simulation and its run. Three simulation types are supported:
- GRAY_BOX: Agent-based.
agent_idandinitial_machine(hostname, username, password, user domain and domain controller IP) are required. Can be launched instantly or on a schedule. - BLACK_BOX: Agent-based.
agent_idandpolicy.inclusionare required,policy.exclusionis rejected andpolicy.domain_nameis optionally used as the domain scope. Can be launched instantly or on a schedule. - RED_TEAM: Stager-based.
stager_idis required instead ofagent_id. Launches instantly only;initial_machineandscheduleare rejected if sent.
The policy object holds the simulation options: inclusion / exclusion scopes (CIDR, IP or hostname), assessment_duration in minutes (30-14400, defaults to 7 days), domain_name, enable_brute_force (SSH/Telnet/VNC/FTP credential brute-forcing, GRAY_BOX/BLACK_BOX only) and enable_opc.
Omit the schedule object to launch the simulation instantly. To schedule it, send frequency (ONCE, DAILY, WEEKLY or MONTHLY), frequency_interval (1-6 for DAILY, 1-3 for WEEKLY/MONTHLY, defaults to 1, ignored for ONCE) and start_time in epoch milliseconds (must be in the future and at most 365 days ahead). For WEEKLY/MONTHLY, the day of the week/month is derived from start_time.
Example
Create and instantly launch a Gray-Box simulation.
curl --request POST \
--url https://api.picussecurity.com/v1/apv/simulations \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer access_token' \
--data '{
"name": "Q3 Gray-Box Simulation",
"description": "Quarterly lateral movement validation",
"simulation_type": "GRAY_BOX",
"agent_id": 102,
"initial_machine": {
"hostname": "10.0.0.10",
"username": "username",
"password": "password",
"user_domain": "USER.DOMAIN",
"domain_controller_ip": "10.0.0.6"
},
"policy": {
"inclusion": ["10.0.0.0/24"],
"exclusion": ["10.0.0.5"],
"assessment_duration": 4320,
"enable_brute_force": false,
"enable_opc": true
}
}'{
"run_uuid": "{run_uuid}",
"simulation_uuid": "{simulation_uuid}"
}Create a Black-Box simulation that runs weekly, starting at the given time.
curl --request POST \
--url https://api.picussecurity.com/v1/apv/simulations \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer access_token' \
--data '{
"name": "Weekly Black-Box Simulation",
"simulation_type": "BLACK_BOX",
"agent_id": 101,
"policy": {
"inclusion": ["10.0.0.0/24"],
"domain_name": "corp.local",
"assessment_duration": 1440
},
"schedule": {
"frequency": "WEEKLY",
"frequency_interval": 1,
"start_time": 1798761600000
}
}'{
"run_uuid": "{run_uuid}",
"simulation_uuid": "{simulation_uuid}"
}Create and instantly launch a Red-Team simulation using a stager.
curl --request POST \
--url https://api.picussecurity.com/v1/apv/simulations \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer access_token' \
--data '{
"name": "Red-Team Simulation",
"simulation_type": "RED_TEAM",
"stager_id": "HONEYBADGER",
"policy": {
"inclusion": ["10.0.0.0/24"],
"assessment_duration": 4320
}
}'{
"run_uuid": "{run_uuid}",
"simulation_uuid": "{simulation_uuid}"
}