Metadata-Version: 2.4
Name: redteam-os-agent
Version: 0.1.2
Summary: Pull-based RedOS worker runtime agent for WORKER_RUNTIME task execution.
Author: nquangit
License: Proprietary
Project-URL: Homepage, https://pypi.org/project/redteam-os-agent/
Keywords: redteam,agent,worker,runtime,automation
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests==2.32.5
Requires-Dist: psutil<8,>=5.9

# RedOS Runtime Agent

The RedOS runtime agent is a pull-based worker process. It authenticates with a
worker token, claims `WORKER_RUNTIME` tasks, runs one non-interactive shell
command at a time, streams output to the control plane, and reports final
results.

The agent is packaged as a separate instance under [`agent/`](./). Its runtime
environment is intentionally separate from the control-plane `.env`.

## PyPI Package

Package name:

```bash
redteam-os-agent
```

The package version is currently sourced from:

```bash
agent/redos_agent/__init__.py
```

If you update the code and want to publish again, you must bump
`redos_agent.__version__` first. PyPI will reject uploading the same version
twice.

## Boundaries

This agent does not install tools, create persistence, open an interactive
terminal, run MCP, perform exploit automation, or choose commands by itself. It
only executes task payloads explicitly created and dispatched by the control
plane.

## Configuration

Required:

```bash
cp agent/.env.example agent/.env
```

Then edit `agent/.env` and set at least:

```bash
REDOS_AGENT_API_URL="http://localhost:5000/api"
REDOS_AGENT_WORKER_TOKEN="rw_<worker_id>_<secret>"
```

## Create A Worker Token

Create or reuse a worker through the operator API, then rotate a worker token:

```bash
curl -sS -X POST "http://localhost:5000/api/workers/$WORKER_ID/token" \
  -H "Authorization: Bearer $REDOS_API_TOKEN"
```

The plaintext token is shown once. Store it in `REDOS_AGENT_WORKER_TOKEN`.

## Run Locally

```bash
python -m venv .agent-venv
. .agent-venv/bin/activate
pip install -r agent/requirements.txt
set -a
. agent/.env
set +a
PYTHONPATH=agent python -m redos_agent
```

If installed from PyPI instead of source, run:

```bash
redteam-os-agent
```

## Install As A Service

After installing from PyPI, you can install and start the agent as a `systemd`
service with one command:

```bash
sudo redteam-os-agent-install
```

The installer will:

1. ask for the RedOS API URL
2. ask for the worker token
3. validate the token with the control plane by sending a heartbeat
4. if validation succeeds, write the service config
5. enable and start the service immediately

The installer writes:

- env file: `/etc/redteam-os-agent/agent.env`
- service file: `/etc/systemd/system/redteam-os-agent.service`

After install:

```bash
systemctl status redteam-os-agent
journalctl -u redteam-os-agent -f
```

If you prefer non-interactive install:

```bash
sudo redteam-os-agent-install \
  --api-url "http://localhost:5000/api" \
  --worker-token "rw_<worker_id>_<secret>" \
  --agent-name "redos-agent-service" \
  --yes
```

## Run With Docker Compose

```bash
cp agent/.env.example agent/.env
# edit agent/.env
docker compose -f agent/docker-compose.agent.yml --env-file agent/.env up --build
```

On Linux, the compose file maps `host.docker.internal` to the host gateway.
Because the compose file now lives under `agent/`, its Docker build context and
env file are fully local to the agent instance.

## Build And Publish To PyPI

### First build

From the repository root:

```bash
python -m venv .publish-venv
. .publish-venv/bin/activate
python -m pip install --upgrade pip build twine
cd agent
python -m build
python -m twine check dist/*
```

This creates:

- `dist/redteam_os_agent-<version>.tar.gz`
- `dist/redteam_os_agent-<version>-py3-none-any.whl`

### First upload

Upload to PyPI:

```bash
cd agent
python -m twine upload dist/*
```

If you want to test the package first, upload to TestPyPI:

```bash
cd agent
python -m twine upload --repository testpypi dist/*
```

### Install after publish

```bash
pip install redteam-os-agent
```

Install and start as a service right after package install:

```bash
sudo redteam-os-agent-install
```

### Rebuild and publish again after code changes

1. Update the code.
2. Bump `agent/redos_agent/__version__`.
3. Rebuild clean artifacts.
4. Upload the new version.

Recommended flow:

```bash
. .publish-venv/bin/activate
cd agent
rm -rf build dist *.egg-info
python -m build
python -m twine check dist/*
python -m twine upload dist/*
```

### Verify published package

```bash
pip install --upgrade redteam-os-agent
redteam-os-agent
```

If you are testing against TestPyPI:

```bash
pip install --index-url https://test.pypi.org/simple/ redteam-os-agent
```

## Dispatch A Runtime Task

Create a harmless task:

```bash
curl -sS -X POST "http://localhost:5000/api/tasks" \
  -H "Authorization: Bearer $REDOS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target":"runtime-agent","command_payload":"whoami"}'
```

Dispatch it for worker-runtime mode:

```bash
curl -sS -X POST "http://localhost:5000/api/tasks/$TASK_ID/dispatch" \
  -H "Authorization: Bearer $REDOS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"WORKER_RUNTIME"}'
```

The agent will claim the task, create a runtime `TaskExecution`, stream output,
and finalize the task result.

To collect artifacts, include `artifact_paths` when creating the task:

```bash
curl -sS -X POST "http://localhost:5000/api/tasks" \
  -H "Authorization: Bearer $REDOS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target":"runtime-agent","command_payload":"printf hello > /tmp/redos-artifact.txt","artifact_paths":["/tmp/redos-artifact.txt"]}'
```

The agent uploads existing artifact files before reporting completion or
failure. Missing files are reported as artifact metadata with status `MISSING`.

## Observe Output

List executions:

```bash
curl -sS "http://localhost:5000/api/tasks/$TASK_ID/executions" \
  -H "Authorization: Bearer $REDOS_API_TOKEN"
```

Watch live SSE output:

```bash
curl -N "http://localhost:5000/api/tasks/$TASK_ID/executions/$EXECUTION_ID/stream?last_id=0-0" \
  -H "Authorization: Bearer $REDOS_API_TOKEN"
```

Read durable logs and final results:

```bash
curl -sS "http://localhost:5000/api/tasks/$TASK_ID/executions/$EXECUTION_ID/logs" \
  -H "Authorization: Bearer $REDOS_API_TOKEN"

curl -sS "http://localhost:5000/api/tasks/$TASK_ID/results" \
  -H "Authorization: Bearer $REDOS_API_TOKEN"
```

List and download artifacts:

```bash
curl -sS "http://localhost:5000/api/tasks/$TASK_ID/artifacts" \
  -H "Authorization: Bearer $REDOS_API_TOKEN"

curl -L "http://localhost:5000/api/tasks/$TASK_ID/artifacts/$ARTIFACT_ID/download" \
  -H "Authorization: Bearer $REDOS_API_TOKEN" \
  -o redos-artifact.bin
```
