Metadata-Version: 2.4
Name: sernixa-agent
Version: 1.5.0
Summary: Sernixa local MCP discovery agent
Author: Sernixa Team
License-Expression: MIT
Project-URL: Changelog, https://github.com/abhishekdhull63/Sernixa.ai-Web/tree/main/packages/sernixa-agent/CHANGELOG.md
Project-URL: Documentation, https://github.com/abhishekdhull63/Sernixa.ai-Web/tree/main/packages/sernixa-agent/README.md
Keywords: sernixa,mcp,discovery,local-agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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

# Sernixa Local Agent

Local MCP discovery agent for Sernixa. It scans only configured hosts, ports,
and paths from the machine where it runs, then optionally syncs evidence-backed
candidates to Sernixa.

## Install

```bash
python -m pip install -e packages/sernixa-agent
```

From a repo checkout, prefer the shared target because it clears stale editable
metadata, reinstalls the package, and prints the loaded `cli.py` path:

```bash
make agent-install-local
make agent-which
```

For internal rollout from a built wheel:

```bash
python -m pip install --upgrade dist/sernixa_agent-1.5.0-py3-none-any.whl
pipx install --force dist/sernixa_agent-1.5.0-py3-none-any.whl
uv tool install --force dist/sernixa_agent-1.5.0-py3-none-any.whl
```

Build and verify release artifacts:

```bash
python packages/sernixa-agent/scripts/release.py --check
cd packages/sernixa-agent
python -m pip install build
python -m build
python scripts/release.py --build
```

`pipx` and `uv tool` are the preferred paths for operators who should not manage
a Python virtual environment directly. Native single-file binaries are not
published yet; use wheel-based distribution for v1.5.

## Initialize

Fast path for one machine:

```bash
curl -fsSL https://raw.githubusercontent.com/abhishekdhull63/Sernixa.ai-Web/main/packages/sernixa-agent/install.sh | sh -s -- --machine-label "Security laptop"
```

The installer prompts for an org-scoped key when one is not already available
through `SERNIXA_AGENT_TOKEN`, `SERNIXA_API_KEY`, or an existing token file. It
installs the requested agent version, writes `~/.sernixa/agent.token` with
`0600` permissions, runs `init`, `diagnose --check-backend`, `enroll`, one
`sync`, and installs a user-level daemon service where supported. The token is
never printed. Install is not verification; the first accepted sync is the
evidence Sernixa can show.

When device-code enrollment is enabled on the API, a first-time operator can
avoid pasting a raw API key for inventory enrollment:

```bash
curl -fsSL https://raw.githubusercontent.com/abhishekdhull63/Sernixa.ai-Web/main/packages/sernixa-agent/install.sh | sh -s -- --device-enroll --machine-label "Security laptop"
```

Device-code enrollment creates the enrollment inventory record after an
authenticated admin approves the displayed code. It does not yet mint a
long-lived daemon sync token, so the first accepted sync and auto-syncing state
still require a configured sync token until sync-token minting ships. Backend
completion returns `next_step_token_status=requires_manual_sync_token` to make
that second step explicit. Treat the current pilot path as four steps:
enroll inventory, configure the sync token through the tenant secret channel,
install it with `sernixa-agent rotate-token --new-token-stdin`, run
`sernixa-agent sync`, then start daemon mode after accepted sync. See
`docs/mcp-local-agent-pilot-rollout.md` before enabling a tenant pilot.

Create a non-secret config and private token file:

```bash
sernixa-agent init --machine-label "Security laptop"
```

Install an org-scoped Sernixa sync token through stdin:

```bash
printf '%s\n' "$APPROVED_SYNC_TOKEN" | sernixa-agent rotate-token --new-token-stdin --token-file ~/.sernixa/agent.token --check-backend
```

The token needs access to MCP registry read/discovery ingestion for the target
organization. The agent sends it only as an HTTP bearer token and never includes
it in scan JSON, logs, or evidence.

Check local readiness without scanning endpoints:

```bash
sernixa-agent status
sernixa-agent status --json
sernixa-agent diagnose --check-backend
sernixa-agent enroll
sernixa-agent enroll-device --open-browser
sernixa-agent sync
sernixa-agent daemon
```

`enroll` registers stable machine identity, non-secret label, and current agent
version in Sernixa inventory. It does not scan endpoints or claim the machine is
continuously online.

## Auto-Discovery

Auto-discovery v2 means the helper is installed and enrolled once, usually by
the standard installer or fleet deployment, then kept running as a daemon. After
the first accepted sync appears in the MCP Control Plane, normal admins use
**Auto Discover now** in the web UI. The daemon pulls scoped jobs and reports
observations; Sernixa treats only accepted sync events as discovery evidence,
and enrollment alone remains inventory evidence.

CLI commands below are support, debugging, and rollout tools. They are not the
recurring customer workflow after the helper is installed and syncing.
The web/API Auto Discover job path is controlled by `MCP_AUTO_DISCOVER_ENABLED`
and remains off by default until an operator enables the rollout.

```bash
sernixa-agent daemon --interval 300
sernixa-agent daemon --once
sernixa-agent run
sernixa-agent install-service --platform auto
sernixa-agent uninstall-service --platform auto --stop
sernixa-agent status --json
```

Defaults:

- successful runs sleep for 300 seconds
- intervals are bounded from 30 seconds to 24 hours
- transient failures use exponential backoff with jitter, capped at 900 seconds
- scans never overlap inside a process, and a lock file prevents two daemon
  processes from running the same agent loop
- non-secret daemon state is written to `~/.sernixa/agent-state.json`
- the default daemon lock file is `~/.sernixa/agent.lock`

Fail-closed errors such as missing auth, rejected tokens, disabled or revoked
machines, unsupported payload versions, invalid signatures, and clock skew stop
the daemon instead of silently degrading to partial success. Network and 429/5xx
failures are retried with backoff and recorded in local state.

`status --json` reports `daemon.health`, `daemon.status`,
`last_successful_scan_at`, `last_successful_sync_at`, `backoff_seconds`,
`next_run_at`, `last_error_category`, `configured_lock_file`, and user-service
installation state. It never prints the token value.

User-level service helpers write templates only; they do not mint tokens or
enable services without operator action:

```bash
sernixa-agent install-service --platform linux
systemctl --user daemon-reload
systemctl --user enable --now sernixa-agent.service
journalctl --user -u sernixa-agent.service -f

sernixa-agent install-service --platform macos
launchctl load ~/Library/LaunchAgents/com.sernixa.agent.plist
tail -f ~/Library/Logs/sernixa-agent.err.log
```

Generated services run `sernixa-agent daemon --service-mode`. In service mode,
a deliberate fail-closed condition writes state and exits successfully so the
service manager does not restart forever on a revoked or invalid key. Unexpected
process crashes still restart.

## Upgrade

Print the supported internal upgrade commands and compatibility expectations:

```bash
sernixa-agent upgrade
sernixa-agent upgrade --json
```

For existing `pipx` installs, distribute the new wheel and run:

```bash
pipx install --force dist/sernixa_agent-1.5.0-py3-none-any.whl
sernixa-agent diagnose --check-backend
sernixa-agent enroll
sernixa-agent sync
```

For `uv tool` installs:

```bash
uv tool install --force dist/sernixa_agent-1.5.0-py3-none-any.whl
sernixa-agent diagnose --check-backend
sernixa-agent sync
```

Saved scans with unsupported schemas are not migrated automatically. After an
upgrade, rerun `sernixa-agent scan` or `sernixa-agent sync` so the backend
receives a current payload.

## Scan

```bash
sernixa-agent scan
sernixa-agent scan --ports 3000,8000,8080
sernixa-agent scan --hosts 127.0.0.1 --paths /mcp,/sse --output /tmp/sernixa-mcp-scan.json
```

`scan` prints a safe count/source summary. Pass `--output` to explicitly write a
`sernixa.mcp.local_agent.discovery.v1` payload to a local file. It does not
inspect arbitrary networks unless you explicitly pass hosts. Default candidate
paths include `/mcp`, `/sse`, `/messages`, `/rpc`, `/jsonrpc`, `/api/mcp`, and
well-known MCP metadata paths.

To force execution from this checkout and verify the loaded module:

```bash
make agent-install-local
make agent-version-check
make agent-which
make agent-cli ARGS="sync"
./run_dev_cli.sh --version-check
./run_dev_cli.sh sync
```

The version check is part of the packaged `sernixa-agent` CLI and prints the
executing `cli.py` path plus active sync candidate whitelist. `which
sernixa-agent` normally points at a Python bin shim; `sernixa-agent
--version-check` is the authoritative check for the source file loaded by that
shim. It never prints discovery results or environment values.

## Sync

Preferred local setup uses the token file created by `init`:

```bash
sernixa-agent sync
```

For CI or ephemeral sessions, environment variables are also supported:

```bash
export SERNIXA_API_KEY=srnx_live_...
sernixa-agent sync --api-base-url https://api.sernixa.com
```

Use the API origin for sync. The CLI canonicalizes `https://sernixa.com` and
`https://www.sernixa.com` to `https://api.sernixa.com` to avoid routing local
agent sync through the web app.

You may also set `SERNIXA_AGENT_TOKEN`; it takes precedence over
`SERNIXA_API_KEY`. `--token-file` and `--token-env` can override the configured
auth source.

Sync retries transient network and 429/5xx failures, sends a stable
`Idempotency-Key`, and keeps deterministic endpoint ordering and stable
candidate `result_id` values for repeated runs. Retry diagnostics are written
to stderr so JSON responses on stdout stay parseable.

The agent never captures environment variables, files, request bodies, or
secrets from discovered endpoints.

## Discovery-Only and Shadow AI Candidates

Use `discover-only` when you want reviewable candidates without enrolling the
machine in fleet inventory:

```bash
sernixa-agent discover-only --ports 3000,8000 --paths /mcp,/sse
sernixa-agent discover-only --shadow-scope . --sync
sernixa-agent discover-only --include-default-configs --include-processes --sync
sernixa-agent discover-only --no-endpoint-scan --shadow-scope /repo --output shadow-candidates.json
```

Discovery-only mode labels every candidate as `discovered_not_enrolled` and
adds guardrail evidence explaining that it is not enrollment, accepted sync
proof, or verification. `--shadow-scope` is explicit and bounded: the agent
inspects only supplied files/directories, skips common dependency/cache folders,
looks for MCP and AI-agent markers in config/code/container files, and records
markers plus file location metadata without copying secret values.

`--sync` sends candidates to the existing Sernixa discovery review queue through
`POST /api/mcp/discovery/sync`. It does not import or register anything;
an admin still has to approve for enrollment, ignore, mark out of scope, defer,
or import candidates separately. Each review action records actor, timestamp,
reason, evidence source, and evidence codes.
Process discovery is opt-in and reads process names only; command arguments and
environment variables are not captured.

## Config

By default the agent reads `./sernixa-agent.json` first and then
`~/.sernixa/agent.json`.

Precedence is:

1. CLI flags
2. Config file
3. Environment variables such as `SERNIXA_API_BASE_URL`, `SERNIXA_AGENT_ID`, and `SERNIXA_MACHINE_LABEL`
4. Built-in defaults

```json
{
  "agent_id": "sernixa-agent-workstation",
  "api_base_url": "https://api.sernixa.com",
  "daemon_interval_seconds": 300,
  "daemon_lock_file": "~/.sernixa/agent.lock",
  "daemon_max_backoff_seconds": 900,
  "daemon_stale_after_seconds": 900,
  "daemon_state_file": "~/.sernixa/agent-state.json",
  "hosts": ["127.0.0.1"],
  "machine_label": "Security laptop",
  "paths": ["/mcp", "/sse", "/api/mcp"],
  "ports": [3000, 8000, 8080],
  "sync_retries": 2,
  "sync_timeout_seconds": 10.0,
  "timeout_seconds": 1.5,
  "token_file": "~/.sernixa/agent.token"
}
```

Unknown config keys and wrong JSON types fail fast with exit code `3`.
Missing auth exits with code `4`. Sync failures exit with code `5`.

## Machine Inventory

Each scan includes a stable, non-secret `machine_id`, the optional
`machine_label`, `agent_version`, `scan_fingerprint`, and `payload_schema`. The
raw hostname is not emitted. Recent syncs in Sernixa use these fields to show
which enrolled machine produced each scan.

Change a label by editing `machine_label` in `~/.sernixa/agent.json` or by
running commands with `--machine-label`. The stable `machine_id` does not change,
so history remains tied to the same enrolled machine.

Rotate a token with the admin dashboard and local handoff loop:

1. Security admin marks token rotation requested for the machine.
2. Operator receives the replacement token through the approved secret channel.
3. Operator replaces the local token without echoing it:

```bash
sernixa-agent rotate-token --new-token-stdin --check-backend
```

For non-interactive shells, use `--new-token-env SERNIXA_REPLACEMENT_TOKEN`.
The command writes only the configured token file, sets mode `0600`, and never
prints the old or new token. It does not mint tokens or prove the token has
synced.

4. Admin marks the dashboard rotation as local install complete after the local
   file is replaced. This is an audit marker, not backend verification.
5. Operator runs `sernixa-agent sync`. The dashboard changes to
   `verified_after_rotation` only after Sernixa receives a successful sync from
   that machine after the install marker.

`sernixa-agent diagnose --check-backend` proves backend reachability, not token
verification. The `rotate-token` command prints the expected verification step
as `sernixa-agent sync` so support can distinguish local replacement from
dashboard verification. If sync fails, share CLI stderr with support; support
can log reminder, backend recheck, owner-contact, or revoke/re-enroll escalation
actions in the dashboard. Those actions are audit records only; they do not
deliver tokens, re-enable machines, or verify rotation.
Do not place tokens in scan output, config commits, shell history, or rollout
scripts.

## Compatibility

The backend accepts `sernixa.mcp.local_agent.discovery.v1` payloads from
`sernixa-agent >=1.0,<2.0`. Saved scans with another payload schema or missing
required fields are rejected before sync.
