storm-pulse-agent 0.1.6__tar.gz

storm_pulse_agent-0.1.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mathew Storm
+
+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.

storm_pulse_agent-0.1.6/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: storm-pulse-agent
+Version: 0.1.6
+Summary: Secure server management agent for Storm Developments infrastructure
+License-Expression: MIT
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: websockets>=14.0
+Requires-Dist: psutil>=6.0
+Requires-Dist: cryptography>=48.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.0; extra == "dev"
+Requires-Dist: mypy>=1.13; extra == "dev"
+Requires-Dist: types-psutil>=6.0; extra == "dev"
+Requires-Dist: import-linter>=2.0; extra == "dev"
+Dynamic: license-file

storm_pulse_agent-0.1.6/README.md

@@ -0,0 +1,107 @@
+# Storm Pulse Agent
+
+[![CI](https://git.stormdevelopments.ca/official-public/storm-pulse/actions/workflows/test.yml/badge.svg)](https://git.stormdevelopments.ca/official-public/storm-pulse/actions)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Typed: mypy strict](https://img.shields.io/badge/mypy-strict-blue.svg)](https://mypy-lang.org/)
+
+Secure server management agent for [Storm Developments](https://stormdevelopments.ca). Connects outbound to a Django dashboard over WebSocket with mTLS, pushes system metrics, and executes whitelisted deploy commands. Zero listening ports.
+
+## How It Works
+
+1. Agent connects **outbound** to the dashboard. Nginx terminates mTLS.
+2. Sends a `register` message (including its available commands list), then pushes metrics every 15s (CPU, memory, disk, load, containers).
+3. Dashboard sends HMAC-signed commands. Agent verifies signature, nonce, and expiry before executing.
+4. Commands run via `subprocess.run(shell=False)` against a strict whitelist. Custom commands can be added via config with optional overridable parameters (regex-validated). No shell injection possible.
+
+Read the [Protocol Specification](https://git.stormdevelopments.ca/official-public/storm-pulse/wiki/Protocol-Specification) for exact information.
+
+## Security
+
+Five layers, each independent:
+
+- **Network** -- No inbound ports. Agent initiates all connections.
+- **Transport** -- mTLS with per-agent certs from a private CA.
+- **Application** -- HMAC-SHA256 + nonce + expiry on every command.
+- **Execution** -- Whitelisted commands only. Absolute paths. `shell=False`. Config placeholders from local config only; runtime params are regex-validated.
+- **OS** -- Dedicated user. Systemd sandboxing.
+
+See the [Security Architecture](https://git.stormdevelopments.ca/official-public/storm-pulse/wiki/Security-Architecture) wiki page for the full design.
+
+## Setup
+
+Requires Python 3.12+. Three runtime deps: `websockets`, `psutil`, `cryptography`.
+
+Install from source:
+
+```bash
+pip install git+https://git.stormdevelopments.ca/official-public/storm-pulse.git
+```
+
+For full setup instructions (system user, permissions, systemd, firewall), see the [Setup Guide](https://git.stormdevelopments.ca/official-public/storm-pulse/wiki/Setup-Guide).
+
+## CLI
+
+```
+stormpulse enroll ENDPOINT AGENT_ID TOKEN [--creds-dir DIR] [--force]
+stormpulse init [--creds-dir DIR] [--force]
+stormpulse run [CONFIG]
+stormpulse status [CONFIG]
+stormpulse garage init [--config PATH] [--garage-config PATH] [--force]
+stormpulse logging init [--config PATH]
+stormpulse --version
+```
+
+**enroll** -- One-time enrollment. Generates an EC P-256 keypair, sends a CSR to the dashboard, writes the signed cert + CA cert + HMAC key to `/etc/stormpulse/`. The private key never leaves the machine.
+
+**init** -- Interactive setup wizard. Generates config, creates systemd service, sets permissions. Run after enrollment. Auto-detects Garage installations and running Docker containers and offers to enable integration / log shipping.
+
+**run** -- Starts the agent. Connects to the dashboard, sends heartbeats and metrics, executes commands. Reconnects automatically with exponential backoff.
+
+**status** -- Local inspection. Shows version, agent ID, config path, dashboard URL, certificate expiry, nonce DB entry count, and whether the agent process is running. No network required.
+
+**garage init** -- Detects a Garage S3 node and appends a `[garage]` section to an existing `stormpulse.toml`. Auto-detects container name from docker-compose.yml. Use `--force` to overwrite an existing `[garage]` section.
+
+**logging init** -- Detects running Docker containers and appends `[[log_groups]]` blocks for each, using `source_type = "docker"` and the `docker_raw` parser. Skips containers already present in the config. See [Log Shipping](https://git.stormdevelopments.ca/official-public/storm-pulse/wiki/Logging) for details.
+
+## Configuration
+
+Run `stormpulse init` to generate a config interactively - see the [Setup Guide](https://git.stormdevelopments.ca/official-public/storm-pulse/wiki/Setup-Guide). Key settings:
+
+| Section | Field | Description |
+|---------|-------|-------------|
+| `agent` | `id` | Unique identifier for this server |
+| `agent` | `pulse_token` | UUID from the Server record in the dashboard |
+| `agent` | `disabled_commands` | List of command names to remove from the registry (optional) |
+| `dashboard` | `url` | WebSocket URL (`wss://...`) |
+| `project` | `project_dir` | Absolute path to the deployed project |
+| `project` | `compose_file` | Absolute path to docker-compose.yml |
+| `project` | `env_file` | Absolute path to `.env` file (optional, passed as `--env-file` to docker compose) |
+| `commands.*` | | Custom commands (optional, see example config) |
+| `garage` | `enabled` | Enable Garage S3 integration (optional, default: absent) |
+| `garage` | `container_name` | Docker container name for Garage (e.g. `garaged`) |
+| `garage` | `config_path` | Path to Garage config file |
+| `garage` | `state_push_interval_seconds` | How often to refresh Garage state (default: 30) |
+
+## Documentation
+
+- [Setup Guide](https://git.stormdevelopments.ca/official-public/storm-pulse/wiki/Setup-Guide) -- Full install, enrollment, systemd, permissions
+- [Customize Commands](https://git.stormdevelopments.ca/official-public/storm-pulse/wiki/Customize--Commands) -- How to disable existing commands, or whitelist new commands
+- [Log Shipping](https://git.stormdevelopments.ca/official-public/storm-pulse/wiki/Logging) -- Tailing container and file logs to the dashboard
+- [Garage Integration](https://git.stormdevelopments.ca/official-public/storm-pulse/wiki/Garage-Integration) -- Garage S3 node management
+- [Protocol Specification](https://git.stormdevelopments.ca/official-public/storm-pulse/wiki/Protocol-Specification) -- Message formats, envelope structure, versioning
+- [Security Architecture](https://git.stormdevelopments.ca/official-public/storm-pulse/wiki/Security-Architecture) -- Threat model, five security layers
+
+## Develop
+
+```bash
+git clone https://git.stormdevelopments.ca/official-public/storm-pulse.git && cd storm-pulse
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+mypy .          # strict
+make fitness    # architecture + security invariants
+```
+
+## License
+
+MIT - see [LICENSE](LICENSE).

storm_pulse_agent-0.1.6/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=69.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "storm-pulse-agent"
+version = "0.1.6"
+description = "Secure server management agent for Storm Developments infrastructure"
+requires-python = ">=3.12"
+license = "MIT"
+dependencies = [
+    "websockets>=14.0",
+    "psutil>=6.0",
+    "cryptography>=48.0.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=1.0", "mypy>=1.13", "types-psutil>=6.0", "import-linter>=2.0"]
+
+[project.scripts]
+stormpulse = "stormpulse.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.mypy]
+strict = true
+python_version = "3.12"
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+strict = false
+check_untyped_defs = true
+
+[tool.setuptools.packages.find]
+include = ["stormpulse*"]

storm_pulse_agent-0.1.6/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

storm_pulse_agent-0.1.6/storm_pulse_agent.egg-info/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: storm-pulse-agent
+Version: 0.1.6
+Summary: Secure server management agent for Storm Developments infrastructure
+License-Expression: MIT
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: websockets>=14.0
+Requires-Dist: psutil>=6.0
+Requires-Dist: cryptography>=48.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.0; extra == "dev"
+Requires-Dist: mypy>=1.13; extra == "dev"
+Requires-Dist: types-psutil>=6.0; extra == "dev"
+Requires-Dist: import-linter>=2.0; extra == "dev"
+Dynamic: license-file

storm_pulse_agent-0.1.6/storm_pulse_agent.egg-info/SOURCES.txt

@@ -0,0 +1,76 @@
+LICENSE
+README.md
+pyproject.toml
+storm_pulse_agent.egg-info/PKG-INFO
+storm_pulse_agent.egg-info/SOURCES.txt
+storm_pulse_agent.egg-info/dependency_links.txt
+storm_pulse_agent.egg-info/entry_points.txt
+storm_pulse_agent.egg-info/requires.txt
+storm_pulse_agent.egg-info/top_level.txt
+stormpulse/__init__.py
+stormpulse/__main__.py
+stormpulse/agent.py
+stormpulse/auth.py
+stormpulse/config.py
+stormpulse/enroll.py
+stormpulse/metrics.py
+stormpulse/protocol.py
+stormpulse/status.py
+stormpulse/caddy/__init__.py
+stormpulse/caddy/commands.py
+stormpulse/caddy/init.py
+stormpulse/caddy/sync.py
+stormpulse/cli/__init__.py
+stormpulse/cli/caddy.py
+stormpulse/cli/enroll.py
+stormpulse/cli/garage.py
+stormpulse/cli/init.py
+stormpulse/cli/log.py
+stormpulse/cli/run.py
+stormpulse/cli/status.py
+stormpulse/commands/__init__.py
+stormpulse/commands/deploy.py
+stormpulse/commands/jobs.py
+stormpulse/commands/registry.py
+stormpulse/garage/__init__.py
+stormpulse/garage/clear_bucket.py
+stormpulse/garage/commands.py
+stormpulse/garage/delete_provisioned_bucket.py
+stormpulse/garage/discover.py
+stormpulse/garage/init.py
+stormpulse/garage/parse.py
+stormpulse/garage/provision_additional_key.py
+stormpulse/garage/provision_bucket.py
+stormpulse/garage/rotate_key.py
+stormpulse/garage/runner.py
+stormpulse/garage/s3.py
+stormpulse/garage/set_cors.py
+stormpulse/garage/state.py
+stormpulse/garage/walk_bucket_stats.py
+stormpulse/init/__init__.py
+stormpulse/init/checks.py
+stormpulse/init/compose.py
+stormpulse/init/files.py
+stormpulse/init/generate.py
+stormpulse/init/orchestrator.py
+stormpulse/init/prompts.py
+stormpulse/init/registry.py
+stormpulse/init/system.py
+stormpulse/logging/__init__.py
+stormpulse/logging/init.py
+stormpulse/logging/parsers.py
+stormpulse/logging/positions.py
+stormpulse/logging/shipper.py
+stormpulse/logging/tailer.py
+stormpulse/logging/writer.py
+tests/test_agent.py
+tests/test_auth.py
+tests/test_commands.py
+tests/test_config.py
+tests/test_enroll.py
+tests/test_init.py
+tests/test_integration.py
+tests/test_jobs.py
+tests/test_metrics.py
+tests/test_protocol.py
+tests/test_status.py

storm_pulse_agent-0.1.6/storm_pulse_agent.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

storm_pulse_agent-0.1.6/storm_pulse_agent.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+stormpulse = stormpulse.cli:main

storm_pulse_agent-0.1.6/storm_pulse_agent.egg-info/requires.txt

@@ -0,0 +1,10 @@
+websockets>=14.0
+psutil>=6.0
+cryptography>=48.0.0
+
+[dev]
+pytest>=8.0
+pytest-asyncio>=1.0
+mypy>=1.13
+types-psutil>=6.0
+import-linter>=2.0

storm_pulse_agent-0.1.6/storm_pulse_agent.egg-info/top_level.txt

@@ -0,0 +1 @@
+stormpulse

storm_pulse_agent-0.1.6/stormpulse/__init__.py

@@ -0,0 +1,5 @@
+"""Storm Pulse Agent - secure server management over WebSocket."""
+
+from importlib.metadata import version
+
+__version__ = version("storm-pulse-agent")

storm_pulse_agent-0.1.6/stormpulse/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as ``python -m stormpulse``."""
+
+from stormpulse.cli import main
+
+if __name__ == "__main__":
+    main()