Touchless NodeZero Deployment
h3-cli: Touchless NodeZero deployment using the h3-cli agent
You can now deploy NodeZero automatically on your Docker Host using the h3-cli agent.
All internal pentests require that you deploy NodeZero on a Docker Host inside your network. This is normally done by manually copy+pasting the NodeZero Launch Script and running it on your machine.
To launch NodeZero automatically, you first spin up an agent process on your Docker Host, using the h3-cli. The h3-cli agent is a long-lived daemon process that periodically polls the H3 API and launches NodeZero automatically on the local machine whenever a new pentest is created and assigned to that agent.
If you are running external pentests, NodeZero is deployed automatically to the H3 cloud and the h3-cli agent is not required.
1. Spin up an agent (internal pentests only)
The command below will spin up an agent named my-agent
on the local machine, and log its
output to /tmp/my-agent.log
:
h3 start-agent my-agent /tmp/my-agent.log
To verify the agent has registered itself with H3, run the command below:
h3 agents
You should see an entry for the agent my-agent
that you just started.
Verify agent connectivity by sending it a "hello world":
h3 hello-agent my-agent
tail -f /tmp/my-agent.log
You should see the following hello world message received by your agent in the log. It might take a minute for the message to appear.
[Mon Feb 6 01:38:13 EST 2023] [agent: my-agent] Received agent command: {
"uuid": "aca96d72-13a2-487e-b6f1-fda2860e4aee",
"agent_uuid": "8c53d4e7-32a4-4d26-a02e-b83bb5770c19/my-agent",
"command": "hello-world",
"received_at": "2023-02-06T06:38:13.387793",
"row_created_at": "2023-02-06T06:38:06.553829"
}
[Mon Feb 6 01:38:13 EST 2023] [agent: my-agent] Running command in a separate process: hello-world
[Mon Feb 6 01:38:13 EST 2023] [agent: my-agent] Sleeping for 60 seconds
{
"data": {
"hello": "world!"
}
}
2. Provision a pentest and assign it to the agent
To create a new pentest and assign it to an agent, use the agent_name
parameter:
h3 run-pentest '{"agent_name": "my-agent", "op_name": "Pentest created via h3-cli and launched via agent"}'
In a minute or so you should see the agent kick off the NodeZero Launch Script for the newly created pentest. You can monitor the agent process by tailing the log:
tail -f /tmp/my-agent.log
The NodeZero Launch Script will download and run the NodeZero Docker container
on the local machine, just as if you had copy+pasted the curl
command from the Portal.
You can view the newly created pentest via:
h3 pentest
3. Useful agent commands
You can list your registered agents via:
h3 agents
You can show any active agent processes on the local machine via:
h3 ps-agent
Finally you can kill all agent processes on the local machine via:
h3 stop-agent