Metadata-Version: 2.4
Name: hb-client
Version: 0.5.5
Summary: Secure heartbeat client for the Nuclei monitoring ecosystem
Author-email: "J. Will Pierce" <willp@users.noreply.github.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/willp/heartbeat-client
Project-URL: Repository, https://github.com/willp/heartbeat-client
Project-URL: Documentation, https://github.com/willp/heartbeat-client/blob/main/README.md
Project-URL: Issues, https://github.com/willp/heartbeat-client/issues
Project-URL: Changelog, https://github.com/willp/heartbeat-client/blob/main/CHANGELOG.md
Keywords: heartbeat,monitoring,nuclei,client,heartbeat-monitoring
Classifier: Development Status :: 3 - Alpha
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: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=41.0.0
Requires-Dist: filelock>=3.12.0
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: pytest>=8.3.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: twine>=5.1.0; extra == "dev"
Provides-Extra: typecheck
Requires-Dist: mypy>=1.11.0; extra == "typecheck"
Provides-Extra: release
Requires-Dist: commitizen>=3.29.0; extra == "release"
Dynamic: license-file

# hb-client

A secure, high-reliability heartbeat client for monitoring your systems
using `hbserver` and `hbwatcher`.

## Project Scope

This repository contains only the Python client library and CLI for sending
heartbeat packets and managing local enrollment keys.

Related repositories:

- `hbserver` (`hb_backend`): API/authentication and key lifecycle services
- `hbwatcher` (`hb_watcher`): monitoring process that evaluates heartbeat data

## Installation

```bash
pip install hb-client
```

See [MIGRATION.md](MIGRATION.md) if upgrading from older distribution or config paths.

This installs:

- the Python package `hb_client`
- the CLI command `hbclient`

## Quick Start

### As a library

```python
from hb_client import HbClient, HbConfig

config = HbConfig(server="hb.example.com", serverport=8333)
client = HbClient(name="my-service", interval=60, config=config)
client.send(task="deployment-complete")
client.close()
```

### From the CLI

```bash
hbclient --server-url https://hb.example.com:8333 login
hbclient --server-url https://hb.example.com:8333 status
hbclient send --app my-service --task deploy --interval 60
```

## Features

- **AES-GCM encrypted UDP transport** with CRC32 integrity
- **OAuth Device Flow** for key management
- **Secure by default** with `strict_security=True`
- **Transparent DNS resolution** with configurable refresh intervals
- **Deterministic key rotation** with jitter to prevent thundering herd
- **Atomic file I/O** for crash-safe credential storage
- **Human-readable duration parsing** (e.g., `6h`, `2.5d`, `3w`)

## Configuration

Enrollment keys are stored under:

- Linux: `$XDG_CONFIG_HOME/hbclient/` or `~/.config/hbclient/`
- macOS: `~/Library/Application Support/hbclient/`
- Windows: `%APPDATA%/hbclient/`

## Security Mode (`strict_security`)

`HbClient` accepts `strict_security` (default: `True`). If enrollment is missing, construction raises `RuntimeError` with guidance to run:

```bash
hbclient --server-url https://hb.example.com:8333 login
```

## CLI Reference

```
hbclient [--server SERVER] [--serverport PORT] [--server-url URL] COMMAND
```

## Development

```bash
pip install -e ".[dev]"
make test
make pre-release
```

## Releasing

```bash
pip install -e ".[release]"
cz bump
make pre-release
python -m twine upload dist/hb_client-<version>*
```

## License

Apache-2.0 — see [LICENSE](LICENSE)
