Metadata-Version: 2.4
Name: astrix-openclaw-scanner
Version: 0.1.3
Summary: Detect OpenClaw AI agent installations across your organization via EDR telemetry (CrowdStrike, Microsoft Defender).
Author: Astrix
License: GNU Affero General Public License v3 or later (AGPL-3.0-or-later)
Project-URL: Homepage, https://astrix.security/
Keywords: edr,crowdstrike,microsoft-defender,openclaw,security,discovery
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: mypy>=1.13.0; extra == "dev"
Requires-Dist: types-requests>=2.28.0; extra == "dev"
Dynamic: license-file

# Astrix Openclaw Scanner

Detect OpenClaw AI agent installations across your organization via EDR telemetry. The **lookback period** (how many days of EDR data to search) is configurable via the `--days-back` option; the default is 14 days.

## What It Detects

This tool searches your EDR for evidence of OpenClaw/Clawdbot AI agent activity. Detection is based on **pattern matching in process names/command lines**; this can produce **false positives**, so review results before taking action.

## How Detection Works

**Pattern matching** -- The tool queries EDR telemetry for known patterns associated with OpenClaw (e.g., `openclaw`, `clawdbot`, `moltbot`) in process names, file paths, and command lines. Pattern matching is used because OpenClaw can be installed and executed in many ways -- as a native binary, a Python package, a Docker container, or a system service -- and new methods are added frequently. Broad pattern matching catches all variants without requiring constant updates for each installation method.

**Post-collection filtering** -- Because pattern matching is broad, some results may be noise (e.g., a browser visiting `openclaw.ai`). The tool filters these by extracting the binary/executable name from each event and removing known false positives (browsers, editors, office apps, utilities). Use `--no-filter` to disable this and see all raw matches.

## Supported EDRs

| EDR                    | Status          | Requirements                                    |
| ---------------------- | --------------- | ----------------------------------------------- |
| **CrowdStrike**        | ✅ Full support | API credentials with NGSIEM Read/Write scopes   |
| **Microsoft Defender** | ✅ Full support | App registration with AdvancedQuery permissions |

## Prerequisites

- Python 3.10 or greater
- EDR API credentials (see setup instructions below)

## EDR Setup

### CrowdStrike

1. Go to **Falcon Console** → **Support and resources** → **API Clients and Keys**
2. Create a new API client and assign permissions (scopes):
   - **NGSIEM:WRITE**
   - **NGSIEM:READ**
3. Copy the **Client ID** and **Client Secret**

**Required API Scopes:**

- `NGSIEM:WRITE`
- `NGSIEM:READ`

### Microsoft Defender

1. Go to **Azure Portal** → **App registrations** → **New registration**
2. Create a new app (e.g., "Astrix Openclaw Scanner")
3. Go to **API permissions** → **Add a permission**:
   - Select **APIs my organization uses**
   - Search for **WindowsDefenderATP**
   - Add **Application permission**: `AdvancedQuery.Read.All`
4. Click **Grant admin consent**
5. Go to **Certificates & secrets** → **New client secret**
6. Copy:
   - **Application (client) ID** from Overview
   - **Directory (tenant) ID** from Overview
   - **Client secret value** from Certificates & secrets

**Required API Permissions:**

- `AdvancedQuery.Read.All`

## Installation

```bash
pip install astrix-openclaw-scanner
```

Then run the CLI:

```bash
astrix-openclaw-scanner crowdstrike --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --days-back 14
astrix-openclaw-scanner microsoft_defender --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --tenant-id YOUR_TENANT_ID --days-back 14
```

You can also run as a module: `python -m astrix_openclaw_scanner`.

## Command Line Options

| Option                   | Required      | Default                                    | Description                                             |
| ------------------------ | ------------- | ------------------------------------------ | ------------------------------------------------------- |
| `edr`                    | Yes           | -                                          | EDR to query: `crowdstrike` or `microsoft_defender`     |
| `--client-id`            | Yes           | -                                          | API client ID                                           |
| `--client-secret`        | Yes           | -                                          | API client secret                                       |
| `--tenant-id`            | Defender only | -                                          | Azure tenant ID                                         |
| `--days-back`            | No            | 14                                         | Number of days to look back                             |
| `--no-filter`            | No            | off                                        | Disable post-collection noise filtering                 |
| `--save-raw-events PATH` | No            | (none)                                     | Save raw EDR events to this JSON file; omit to not save |
| `--report-path DIR`      | No            | `./astrix_openclaw_scanner_results/<edr>/` | Directory to write the HTML report                      |

### Known API Limits

| EDR                | Limit                          | Details                                                                                                |
| ------------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------ |
| CrowdStrike        | 10,000 events per 3-day window | The tool divides the search range into 3-day windows. A warning is logged if the limit is reached.     |
| Microsoft Defender | 100,000 events per query       | The Advanced Hunting API returns at most 100,000 results. A warning is logged if the limit is reached. |

If a limit is reached, reduce `--days-back` to narrow the search scope.

### Rate limiting

EDR APIs (CrowdStrike, Microsoft Defender) may apply rate limits. If you see throttling or errors, reduce query scope (e.g. fewer `--days-back`) or run during off-peak times.

## Output

- **HTML report** – By default the report is written to `./astrix_openclaw_scanner_results/<edr>/report_YYYYMMDD_HHMMSS/` relative to where you run the command. Use `--report-path DIR` to change.
- **Raw events** – Only when you pass `--save-raw-events PATH`; the tool writes a JSON file to that path.

Report folder layout:

```
astrix_openclaw_scanner_results/<edr>/report_YYYYMMDD_HHMMSS/
├── index.html
├── script.js
├── styles.css
└── assets/
```

### HTML Report

The HTML report shows:

- **Threats Detected** - Count of unique endpoint/user combinations
- **Endpoint Table** - Hostname, Username, OS, and Last Seen timestamp

Open `index.html` in any browser to view results. The report is self-contained and can be shared.

### Raw Events JSON

The raw events file contains the full EDR response for further analysis:

```json
{
  "collected_at": "2026-02-05T14:49:45Z",
  "event_count": 15,
  "events": [...]
}
```

## License

This project is licensed under the [GNU Affero General Public License v3.0 (AGPL-3.0)](https://www.gnu.org/licenses/agpl-3.0.html) or later. See [LICENSE](LICENSE) for the full text.
