Metadata-Version: 2.4
Name: helladmin-dashboard
Version: 0.1.0a5
Summary: HellAdmin dashboard — approvals, events, chains, monitoring (alpha)
Project-URL: Homepage, https://helladmin.dev
Project-URL: Repository, https://github.com/reimmerse-one/helladmin
Author: Arseniy Kustov
License-Expression: Apache-2.0
Keywords: dashboard,helladmin,monitoring,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: uvicorn[standard]>=0.34
Requires-Dist: websockets>=14.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: llm
Requires-Dist: helladmin-server[llm]>=0.1.0a5; extra == 'llm'
Provides-Extra: wraith
Requires-Dist: helladmin-wraith>=0.1.0a5; extra == 'wraith'
Description-Content-Type: text/markdown

# HellAdmin Dashboard

![status: alpha](https://img.shields.io/badge/status-alpha-black) ![platform: linux](https://img.shields.io/badge/platform-linux-blue) ![license: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue)

Web UI for HellAdmin — AI agent firewall dashboard.

> **Alpha release.** Protect mode is functional. Control mode is planned. APIs may change.

## What it shows

**Protect mode** (single page, default):
- Protection status: Ready / Protecting, Landlock ABI version
- Protected paths with modes (read blocked / write blocked) — click to expand, quick allow buttons (1h/4h/8h)
- Network protection: blocked metadata IPs, allowed TCP ports
- Blocked commands: sudo, nc, mount, ptrace, etc.
- MCP Proxy: registered servers, request stats, API key usage
- Recent blocks feed
- Command history with source detection (ssh:user@ip, container:name, process:pid)

**Control mode** `[planned]`:
- Tabbed navigation: Events, Policies, Approvals, MCP Servers, Forensics
- Approval queue for unknown operations
- Policy editor with live preview
- Full event log

*Control mode is not yet implemented. The features above are planned for a future release.*

## Quick Start

```bash
pip install helladmin-dashboard
```

> **Note:** The dashboard works standalone for viewing, but Protect controls (mode, level, blocks) require `helladmin-server`. Install the full stack with `pip install helladmin` or add `pip install helladmin-server` separately.

### Local (no TLS, no auth)

```bash
helladmin-dashboard
# → http://localhost:8888
```

### Remote access

```bash
HELLADMIN_DASHBOARD_PASSWORD=mysecret helladmin-dashboard --host 0.0.0.0
# → https://0.0.0.0:8888 (auto-generated self-signed cert)
```

## TLS

### Auto-generated certificate (default for remote)

```bash
helladmin-dashboard --host 0.0.0.0
```

Self-signed cert at `~/.helladmin/dashboard-cert.pem`. Browser shows warning — click through.

### Your own certificate

```bash
helladmin-dashboard --host 0.0.0.0 \
  --ssl-certfile /etc/letsencrypt/live/example.com/fullchain.pem \
  --ssl-keyfile /etc/letsencrypt/live/example.com/privkey.pem
```

### Behind nginx

```nginx
server {
    listen 443 ssl http2;
    server_name dashboard.example.com;
    ssl_certificate     /etc/letsencrypt/live/dashboard.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/dashboard.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8888;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

```bash
helladmin-dashboard --no-ssl
```

### No TLS

```bash
helladmin-dashboard --host 0.0.0.0 --no-ssl
```

Only behind a TLS-terminating proxy or on a trusted network.

## Authentication

Without `--password`, binds to localhost with no auth.

For remote access:

```bash
HELLADMIN_DASHBOARD_PASSWORD=mysecret helladmin-dashboard --host 0.0.0.0
```

Or configure users in config YAML:

```yaml
auth:
  users:
    - username: admin
      password_hash: "<hash>"  # generate with: helladmin-dashboard hash-password
      role: admin              # admin | operator | viewer
```

## API

Dashboard backend exposes REST API for the Protect UI:

```
GET  /api/protect/status     Protection state, Landlock ABI, counters
GET  /api/protect/paths      Protected paths with modes and categories
POST /api/protect/paths      Add custom protected path
GET  /api/protect/blocks     Recent blocked events
GET  /api/protect/network    Network protection config
GET  /api/protect/commands   Blocked commands list
GET  /api/protect/allows     Active temporary allows
POST /api/protect/allows     Create temporary allow (1h/4h/8h)
GET  /api/protect/history    Command execution history with source info
GET  /api/protect/proxy/servers   Registered MCP proxy servers with stats
GET  /api/protect/proxy/requests  Recent proxy audit log
```

## CLI

```
helladmin-dashboard [OPTIONS]
helladmin-dashboard hash-password

Options:
  --host HOST             Bind host (default: 127.0.0.1)
  --port PORT             Bind port (default: 8888)
  --config CONFIG         Config file path
  --ssl-certfile FILE     TLS certificate
  --ssl-keyfile FILE      TLS private key
  --no-ssl                Disable automatic TLS
  --no-browser            Don't open browser on localhost
```

## License

Apache-2.0
