# Real Time Response

Real-Time Response (RTR) provides a direct, interactive interface to remote hosts. For automation users, RTR is the primary engine for remote incident response, forensic data collection, and large-scale remediation.

## 1. Understanding the Three Service Collections

RTR is split into three distinct APIs based on the level of authority and the type of data being accessed. Ensure your API Client has the correct **Scopes** assigned for the endpoints you intend to use.

| **Collection**     | **Endpoint Prefix**         | **Purpose**                                                                         | **Required Scope**               |
| ------------------ | --------------------------- | ----------------------------------------------------------------------------------- | -------------------------------- |
| **RTR (Standard)** | `/real-time-response`       | Session management and basic investigation commands (`ls`, `ps`, `kill`).           | `real-time-response:write`       |
| **RTR Admin**      | `/real-time-response`       | Advanced actions: running custom scripts (`runscript`) and uploading files (`put`). | `real-time-response-admin:write` |
| **RTR Audit**      | `/real-time-response-audit` | Forensic history. View logs of what was executed in past sessions.                  | `real-time-response-audit:read`  |

## 2. The Automation Lifecycle (Step-by-Step)

Automating RTR requires managing an asynchronous workflow. You cannot simply "run a command"; you must manage the session and poll for results.

### Step 1: Initialize the Session

All actions start here. You must exchange a `device_id` (AID) for a `session_id`.

**Endpoint**: `POST /real-time-response/entities/sessions/v1`

```bash
POST /real-time-response/entities/sessions/v1 HTTP/1.1
Host: api.crowdstrike.com
Authorization: Bearer `<TOKEN>`
Content-Type: application/json

{
  "device_id": "89890a8a890a890a890a890a890a890a",
  "queue_offline": true
}
```

- **Response**: `session_id` (used in all subsequent command calls).
- **Tip**: Use `queue_offline: true` so the command executes as soon as an offline host checks in.

### Step 2: Dispatch a Command

Once you have a `session_id`, send your command. This returns a `cloud_request_id`.

**Endpoint**: `POST /real-time-response/entities/admin-command/v1`

```bash
POST /real-time-response/entities/admin-command/v1 HTTP/1.1
Host: api.crowdstrike.com
Authorization: Bearer `<TOKEN>`

{
  "base_command": "runscript",
  "command_string": "runscript -CloudMSL='Collect-Logs' -CommandLine='-Target=System'",
  "session_id": "abc-123-your-session-id"
}
```

### Step 3: Iterate Until Output is Available (Polling)

Commands are asynchronous. You must poll the status endpoint until the `complete` flag is `true`.

**Endpoint**: `GET /real-time-response/entities/admin-command/v1?cloud_request_id={ID}&sequence_id=0`

**Logic Loop**:

1. Check `"complete": true`.
2. If `false`, wait 1–2 seconds and repeat.
3. If `true`, move to Step 4.

### Step 4: Iterating on Chunks (Sequencing)

Large outputs are broken into chunks. If the response contains a `next_sequence_id` greater than 0, there is more data to fetch.

**Logic Loop**:

1. Read `stdout` from the current response.
2. If `next_sequence_id > 0`, call the status endpoint again using that new `sequence_id`.
3. Concatenate the output until `next_sequence_id` returns `0`.

---

## 3. Command Capabilities

### Investigation (Read-Only)

- **`ls`**: List directory contents.
- **`ps`**: List running processes.
- **`netstat`**: View network connections.
- **`filehash`**: Calculate MD5/SHA256 of a remote file.

### Remediation (Active Responder / Admin)

- **`kill`**: Terminate a process by ID.
- **`rm`**: Delete a malicious file.
- **`put` / `get`**: Upload a tool to the host or retrieve a file from the host.
- **`runscript`**: Execute a pre-uploaded PowerShell, Bash, or Zsh script.

---

## 4. Managing Scripts and Files (RTR Admin)

Before using `runscript` or `put`, you must manage your library in the Falcon Cloud.

### Uploading a Custom Script

**Endpoint**: `POST /real-time-response/entities/scripts/v1` (Multipart Form Data)

```bash
POST /real-time-response/entities/scripts/v1 HTTP/1.1
Host: api.crowdstrike.com
Authorization: Bearer `<TOKEN>`
Content-Type: multipart/form-data; boundary=boundary

--boundary
Content-Disposition: form-data; name="name"

Remediate.ps1
--boundary
Content-Disposition: form-data; name="content"

## Your PowerShell Logic Here
Stop-Process -Name "malware"
--boundary--
```

---

## 5. Investigating Past Actions (RTR Audit)

Use the Audit API to review what actions were taken programmatically or manually.

**Endpoint**: `GET /real-time-response-audit/combined/sessions/v1?with_command_info=true`

This returns a list of sessions, including:

- `user_id`: Who (or which API key) started the session.
- `logs`: The raw `stdout` and `stderr` of every command executed during that session.
- `cloud_request_ids`: A trail of every specific command issued.

---

## ⚡ Developer Best Practices

1. **Always Delete Sessions**: When your automation is finished, call `DELETE /real-time-response/entities/sessions/v1?session_id={ID}`. Leaving sessions open hits concurrency limits.
2. **Session Pulse**: Sessions expire after 10 minutes of inactivity. For long-running scripts, call the `pulse_session` endpoint to keep the connection alive.
3. **Error Handling**: Always check `stderr` in the command output. A command can be "complete" but have failed (e.g., "Access Denied").
4. **Wait Indicators**: Implement a back-off strategy for polling (e.g., wait 1s, then 2s, then 5s) to avoid unnecessary API rate-limiting.