Skip to content
Dreadnode Dreadnode Dreadnode

Worlds

Create and inspect Worlds manifests, trajectories, and async job state from the dn CLI.

dn worlds ... is the control-plane CLI for Worlds. It revolves around three durable objects:

  • manifest jobs that create a world
  • trajectory jobs that sample attack paths against a world
  • job records that track the async lifecycle

The Worlds mental model

Section titled “The Worlds mental model”
ObjectWhat it is
manifestthe simulated environment itself
trajectoryone or more sampled attack paths through that environment
jobthe async control-plane record that creates the manifest or trajectory

That means most CLI workflows are “submit a job, wait for it, then inspect the durable result.”

A normal Worlds flow

Section titled “A normal Worlds flow”

The easiest way to stay oriented is:

  1. create a manifest job
  2. wait for the job to finish
  3. inspect the manifest you got back
  4. create trajectory jobs against that manifest
  5. inspect the resulting trajectories

Manifest jobs

Section titled “Manifest jobs”

Use dn worlds manifest-create to submit a manifest generation job:

Terminal window
dn worlds manifest-create \
  --server http://127.0.0.1:8000 \
  --api-key "$DREADNODE_API_KEY" \
  --organization dreadnode \
  --workspace main \
  --name corp-ad \
  --preset small \
  --seed 7 \
  --num-users 50 \
  --num-hosts 10 \
  --domain corp.local \
  --json

manifest-create returns a Worlds job record, not the finished manifest object itself. That is why the next useful commands are usually job-wait and then manifest-get.

Terminal window
dn worlds job-wait <job-id> --json
dn worlds manifest-list
dn worlds manifest-get <manifest-id> --json

Once you know the manifest ID, the rest of the inspection commands answer more specific questions:

Terminal window
dn worlds graph-nodes <manifest-id>
dn worlds graph-edges <manifest-id>
dn worlds subgraph <manifest-id> <center-node-id>
dn worlds principals <manifest-id> --query alice
dn worlds principal <manifest-id> <principal-id>
dn worlds principal-details <manifest-id> <principal-id>
dn worlds host <manifest-id> <host-id>
dn worlds host-details <manifest-id> <host-id>
dn worlds commands <manifest-id>
dn worlds manifest-trajectories <manifest-id>

Use those commands like this:

  • graph-nodes, graph-edges, and subgraph help you understand the topology
  • principals, principal, and principal-details are identity-centric views
  • host and host-details are host-centric views
  • commands shows the available action vocabulary for that world
  • manifest-trajectories shows every trajectory already generated from that manifest

The platform UI stays read-only for Worlds. It uses these manifest inspection endpoints to render a bounded semantic graph overview and uses saved trajectory artifacts to render replay after jobs finish, but manifest and trajectory generation should still be started from the CLI.

Trajectory jobs

Section titled “Trajectory jobs”

Use dn worlds trajectory-create to sample trajectories from a completed manifest:

Terminal window
dn worlds trajectory-create \
  --server http://127.0.0.1:8000 \
  --api-key "$DREADNODE_API_KEY" \
  --organization dreadnode \
  --workspace main \
  --manifest-id 11111111-2222-3333-4444-555555555555 \
  --goal "Escalate to Domain Admin" \
  --count 4 \
  --strategy smart-random \
  --mode kali \
  --json

Like manifest creation, trajectory creation returns an async job record first. The durable trajectory objects appear after the job completes.

Terminal window
dn worlds job-wait <job-id> --json
dn worlds trajectory-list
dn worlds trajectory-get <trajectory-id> --json

Agent mode

Section titled “Agent mode”

--mode agent is the mode that confuses people most.

In that mode, the control plane runs an external SDK agent against the Worlds backend instead of using the built-in graph walker. The built-in modes like kali and c2 do not need a runtime binding. agent does.

When you use --mode agent, also pass:

  • --runtime-id
  • --capability-name

and optionally:

  • --agent-name

That tells Worlds which runtime-bound capability snapshot to use for the external agent.

Job commands

Section titled “Job commands”

The Worlds job commands are the async lifecycle view for both manifest generation and trajectory generation:

Terminal window
dn worlds job-list
dn worlds job-get <job-id> --json
dn worlds job-wait <job-id> --json
dn worlds job-cancel <job-id>

dn worlds job-wait polls until the status is completed, failed, or cancelled, and exits non-zero when the terminal status is not completed.

Use the job commands whenever a manifest or trajectory feels “missing.” In Worlds, that usually means the async job has not finished yet, not that the object failed to exist at all.