Metadata-Version: 2.4
Name: akita-sentinel
Version: 0.1.0
Summary: Akita Sentinel — local AI agent monitoring. Watch your agents, scan new skills before they run.
Author-email: PlugPipe Team <hello@plugpipe.ai>
License: MIT License
        
        Copyright (c) 2026 PlugPipe Team
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/PlugPipe/akita-sentinel
Project-URL: Issues, https://github.com/PlugPipe/akita-sentinel/issues
Project-URL: Changelog, https://github.com/PlugPipe/akita-sentinel/releases
Keywords: ai,agent,monitoring,security,governance,sentinel,mcp,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pyyaml>=6.0
Requires-Dist: watchdog>=4.0.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: click>=8.0
Requires-Dist: psutil>=5.9
Provides-Extra: tray
Requires-Dist: pystray>=0.19.5; extra == "tray"
Requires-Dist: Pillow>=10.0.0; extra == "tray"
Requires-Dist: rumps>=0.4.0; sys_platform == "darwin" and extra == "tray"
Provides-Extra: proxy
Requires-Dist: PyJWT>=2.8; extra == "proxy"
Requires-Dist: cryptography>=42.0; extra == "proxy"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-timeout; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://img.shields.io/badge/Akita-Sentinel-blue?style=for-the-badge" alt="Akita Sentinel" />
</p>

<h3 align="center">Know what your AI agent just did.</h3>

<p align="center">
  <a href="https://pypi.org/project/akita-sentinel/"><img src="https://img.shields.io/pypi/v/akita-sentinel?color=blue&label=PyPI" alt="PyPI" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT" /></a>
  <a href="https://github.com/PlugPipe/akita-sentinel/actions"><img src="https://img.shields.io/github/actions/workflow/status/PlugPipe/akita-sentinel/ci.yaml?branch=main&label=CI" alt="CI" /></a>
  <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+" />
  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey" alt="macOS | Windows | Linux" />
</p>

<p align="center">
  AI agents install tools, read files, make API calls, and run code on your machine.<br/>
  Most people have no idea what those tools actually do.<br/><br/>
  <strong>Akita watches every tool call your agent makes, scans new skills before they run, and blocks the dangerous ones.</strong>
</p>

---

## Install

```bash
pip install akita-sentinel
akita sentinel start
```

That's it. Akita discovers your agent frameworks, watches their skill directories, and starts scanning. Your agents never know it's there.

Want the system tray icon and notification popups?

```bash
pip install 'akita-sentinel[tray]'
akita tray start
```

---

## What You Get

<p align="center">
  <img src="docs/screenshots/dashboard.png" alt="Akita Dashboard" width="800" />
</p>

<p align="center"><em>Dashboard — real-time agent status, recent activity, and system health at a glance.</em></p>

### Governance Rules

Define what your agents can and can't do. Rules are enforced automatically — the most dangerous actions are blocked before they execute.

<p align="center">
  <img src="docs/screenshots/governance-rules.png" alt="Governance Rules" width="800" />
</p>

<p align="center"><em>26 built-in rules covering file access, network calls, money transfers, destructive operations, and more.</em></p>

### Trust Center

See exactly which governance rules protect each agent and skill. Connection map shows the relationship between your agents, their skills, and the rules that guard them.

<p align="center">
  <img src="docs/screenshots/trust-center.png" alt="Trust Center" width="800" />
</p>

### Skills Library

Browse and manage every skill your agents have access to. Risk scores, metadata, and scan results in one place.

<p align="center">
  <img src="docs/screenshots/skills.png" alt="Skills Library" width="800" />
</p>

### Agent Management

Monitor connected agents, test connections, and see protection status for each framework.

<p align="center">
  <img src="docs/screenshots/agents.png" alt="Agent Management" width="800" />
</p>

---

## Why Akita?

| Problem | How Akita Helps |
|---|---|
| New skill installed silently | Immediate detection + risk scan |
| Agent calls a suspicious tool | Hook-based governance (blocking for Hermes; advisory alerts for other frameworks) |
| No audit trail of agent activity | Local audit log with 30-day retention |
| Credentials scattered in plaintext files | OS keychain storage (macOS Keychain, Windows Credential Locker) |
| Different agents, different configs | Single sentinel monitors all your agent frameworks |

## Features

- **Auto-discovery** — detects installed agent frameworks automatically
- **Skill scanning** — new or modified skills are scanned before they run
- **Governance enforcement** — Hermes hook-based blocking for governed tool calls (requires hook to be installed; advisory alerts for other frameworks)
- **26 built-in rules** — file access, network calls, money transfers, destructive operations, off-hours gates, and more
- **Trust center** — visual map of which rules protect which agents and skills
- **Local audit log** — every event logged to `~/.akita/audit.db` with 30-day retention
- **OS keychain** — credentials stored in macOS Keychain, Windows Credential Locker, or Linux SecretService (requires libsecret)
- **Cloud pairing** — pair with your Akita account for governance rules and remote visibility
- **Cross-platform** — macOS and Windows with native system tray; Linux on X11/Wayland desktop environments with D-Bus support
- **Start at login** — one command to auto-start on boot (launchd / Registry Run / systemd)

## How It Works

```
┌──────────────────────────────────────────────┐
│  Your Machine                                │
│                                              │
│  ┌───────────┐         ┌──────────────────┐  │
│  │  Hermes   │────────▶│   Tool Call      │  │
│  │  (agent)  │         └──────────────────┘  │
│  └───────────┘                               │
│       │ hooks                                │
│       ▼                                      │
│  ┌──────────────────┐                        │
│  │  Akita Sentinel  │──▶ Scan new skills     │
│  │  (background)    │──▶ Block or allow      │
│  │                  │──▶ Local audit log     │
│  └────────┬─────────┘                        │
│           │                                  │
└───────────┼──────────────────────────────────┘
            │ paired
┌───────────▼─────────────────────────────────┐
│  Akita Cloud                                │
│  (governance rules, remote visibility)      │
└─────────────────────────────────────────────┘
```

The sentinel hooks into the framework's tool-call pipeline and watches skill directories. Your agent runs normally while Akita monitors from the side.

## Supported Frameworks

| Framework | Status |
|---|---|
| [Hermes](https://github.com/anthropics/hermes) | Supported — hook-based governance |
| Claude Code | Coming soon |
| Cursor | Coming soon |

Adding a new framework requires a discovery config + hook adapter.

## Commands

| Command | Description |
|---|---|
| `akita sentinel start` | Start watching your agents |
| `akita sentinel stop` | Stop the sentinel |
| `akita sentinel status` | Check health and watched agents |
| `akita sentinel events` | View recent audit log |
| `akita sentinel pair` | Pair with your Akita account |
| `akita sentinel unpair` | Remove pairing |
| `akita sentinel enable-autostart` | Auto-start at login |
| `akita frameworks check` | Detect installed frameworks |
| `akita tray start` | Start with tray icon and notifications |
| `akita update` | Update to latest version |
| `akita config show` | Show configuration |
| `akita config set <key> <val>` | Set a config value |

## System Tray

Install the tray extras for a live status icon and notification popups:

```bash
pip install 'akita-sentinel[tray]'
akita tray start
```

| Icon | Meaning |
|---|---|
| Blue shield | Watching — all clear |
| Blue + amber dot | Scanning a new skill |
| Amber shield | Warning — suspicious skill detected |
| Red shield | Suspicious activity detected |
| Grey shield | Stopped |

## Configuration

Settings live in `~/.akita/config.yaml`:

```bash
akita config show                                        # show current settings
akita config set update.check_interval_hours 12         # check every 12 hours
akita config set update.auto_update true                # auto-install updates
akita config set registration.base_url https://my.url   # set Akita server URL
```

Auto-update downloads and installs from PyPI using pip. Review the changelog before enabling in security-sensitive environments.

## Start at Login

```bash
akita sentinel enable-autostart          # headless
akita sentinel enable-autostart --tray   # with tray icon
akita sentinel disable-autostart         # remove
```

| Platform | Method | Location |
|---|---|---|
| macOS | launchd Launch Agent | `~/Library/LaunchAgents/io.plugpipe.akita-sentinel.plist` |
| Windows | Registry Run key | `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` |
| Linux | systemd user service | `~/.config/systemd/user/akita-sentinel.service` |

## Security

- **OS keychain** for credential storage — no plaintext secrets on disk
- **Automatic keychain migration** from file-based credentials on first access
- **Unix socket IPC** with owner-only permissions (0600)
- **Cryptographically random** single-use pairing codes
- **Signed governance tokens** (JWT, JWKS-validated) for cloud enforcement
- **Atomic file writes** to prevent partial-state corruption
- **TLS certificate verification** on all outbound connections
- **Path traversal guards** on all filesystem operations
- **Symlink protection** (O_NOFOLLOW) on security-sensitive file reads

## Files

| Path | Description |
|---|---|
| `~/.akita/audit.db` | Local audit log (SQLite, 30-day retention) |
| `~/.akita/sentinel.sock` | IPC socket (owner-only) |
| `~/.akita/config.yaml` | User configuration |
| `~/.akita/credentials.json` | Credentials (migrated to keychain on first access) |

## Developer Install

```bash
git clone https://github.com/PlugPipe/akita-sentinel.git
cd akita-sentinel
pip install -e ".[dev,tray]"
pytest tests/ -x -v
```

## License

MIT — see [LICENSE](LICENSE).

Little Snitch is a registered trademark of Objective Development Software GmbH. Not affiliated.

## Links

- [Akita](https://akita.plugpipe.io) — Personal AI agent hub
- [PlugPipe](https://github.com/PlugPipe) — AI-native infrastructure

---

<details>
<summary>Detection Accuracy Notice</summary>

No detection system is perfect. Akita Sentinel layers rule-based, heuristic, signature,
behavioural-contract, allow/deny-list, and audit-logging techniques to reduce prompt-injection
and tool-misuse risk — but it will miss some threats and may flag some safe activity. The
software is provided "AS IS" / "AS AVAILABLE" with no warranty. By installing it you accept
the residual risk; first-run requires explicit acknowledgement of the detection disclaimer.
Full disclaimer also available via the tray menu > Detection Disclaimer.

</details>
