sernixa-agent 1.5.0__tar.gz

sernixa_agent-1.5.0/PKG-INFO

@@ -0,0 +1,391 @@
+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.