PingTing

PingTing is a local-first network monitoring and security operations toolkit designed for home networks, small labs, and self-hosted environments. It runs on your own hardware, stores everything locally in SQLite, and never phones home. You point it at your subnet, let it learn what "normal" looks like, and it tells you when something changes.

There is a comprehensive operations guide in USERGUIDE.md that covers every configuration option, every CLI command, and day-to-day operational workflows in detail. This README is the short version.

For a detailed implementation snapshot of what is currently in code (command surface, schema shape, reporting workflow capabilities, and control-plane integration contract), see CURRENT_STATE.md.

What It Does

Device inventory and drift detection. PingTing discovers devices on your local subnet using ARP and nmap, tracks their MAC addresses, IP addresses, hostnames, open ports, and service fingerprints, and alerts you when something new shows up or when a known device changes in unexpected ways (new ports, DNS behavior changes, unusual activity windows).

Unknown device classification. When PingTing finds a device it doesn't recognize, it can use a local LLM (any OpenAI-compatible endpoint, such as LM Studio or Ollama) to classify the device based on its network fingerprint. This is entirely optional and runs against your own model — nothing leaves your network.

Breach exposure monitoring. If you provide a Have I Been Pwned API key, PingTing will periodically check your configured email addresses against known breach databases and alert you to new exposures.

Log file monitoring. PingTing watches log files for unexpected warning, error, and critical patterns. It learns what log patterns are normal during a baseline period and then alerts when new patterns appear.

Learning mode and baselines. Before PingTing starts alerting, you run it in learning mode for a configurable window (typically 7 days). During this period it observes your network and builds a baseline of normal behavior — known devices, expected ports, typical DNS queries, log patterns, and activity schedules. Once the learning period ends and you promote the baselines, PingTing starts alerting on deviations from that established normal.

Multi-channel alerting with delivery tracking. Alerts can be dispatched to any combination of local log, webhook, Slack, and SMTP channels. PingTing tracks delivery outcomes for every alert, retries transient failures with exponential backoff, and gives you visibility into what was delivered and what failed.

Operational reporting. PingTing can generate summary reports, historical comparisons, anomaly scores, investigation snapshots, and explainability breakdowns. Reports can be published to webhook or file sinks, and failed publishes land in a dead-letter queue with full replay tooling.

Proactive escalation workflows. For teams that want on-call handoff support, PingTing can build escalation bundles, track acknowledgements and ownership, send SLA-based reminders, and produce handoff markdown documents.

Built-In Agents

Agent	What it does
network_scanner	Discovers devices on your subnet, detects unknown devices, checks for port drift, DNS behavior changes, and schedule deviations. Supports quick scans (ARP-based) and full scans (nmap with OS fingerprinting and service detection).
breach_monitor	Checks configured email addresses against the Have I Been Pwned API and generates findings for new breach exposures.
log_monitor	Tails configured log files, extracts warning/error/critical lines, and generates findings when patterns appear that weren't seen during baseline learning.

How It Works

1. Collect: An agent gathers raw signals — the network scanner runs ARP and nmap, the breach monitor queries the HIBP API, the log monitor reads new log lines.
2. Analyze: The agent converts raw signals into structured findings with severity, confidence scores, and contextual metadata.
3. Precision controls: Before storage, pre-store hooks attach confidence metadata and deduplicate fingerprints to reduce noise and suppress duplicate alerts.
4. Persist and alert: Findings are saved to SQLite. If they meet the configured severity floor and the alert channels are set up, dispatches go out with retry and delivery tracking.
5. Report: Scheduled or on-demand reporting jobs summarize health, detect anomalies, attribute findings across agents, and generate escalation bundles for operational handoff.

Prerequisites

• Python 3.11 or newer.

• arp and ping available on your PATH. These are used for quick device discovery and connectivity probing. They ship with macOS and most Linux distributions.

• nmap for full scan mode and richer fingerprinting. Quick scans work without it, but full scans (run network_scanner --full) require nmap. Install it with:

  # macOS
  brew install nmap
  
  # Debian / Ubuntu
  sudo apt-get update && sudo apt-get install -y nmap

  Full nmap -O fingerprinting may require elevated privileges. PingTing automatically falls back to unprivileged scan modes when it can't escalate. See the User Guide for a hardened sudoers setup that grants root only for the exact nmap command PingTing needs.

• A local LLM endpoint (optional) if you want unknown device classification. Any OpenAI-compatible API works — LM Studio, Ollama with an OpenAI-compatible wrapper, vLLM, etc. Set llm.base_url and llm.model in your config.

• A Have I Been Pwned API key (optional) if you want breach monitoring. Set the HIBP_API_KEY environment variable or configure it in the agents section. HIBP access policy/pricing is managed by HIBP.

• Outbound connectivity to any alert/report sinks you configure (Slack webhooks, SMTP servers, webhook endpoints).

• macOS launchd for the service commands that install PingTing as a background service. These commands are macOS-specific.

Quick Start

# Create a virtual environment and install
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

# Initialize config, directories, and database
python -m pingting init

# Edit the generated config for your environment
$EDITOR config/pingting.yaml

# Verify everything is working
python -m pingting health    # checks LLM endpoint reachability
python -m pingting doctor    # checks config, database, tools, channels
python -m pingting status    # shows runtime overview

# Run an agent manually
python -m pingting run network_scanner
python -m pingting run network_scanner --full

# Start the scheduler daemon
python -m pingting start

What to Configure First

Before running agents for real, edit config/pingting.yaml and set at least:

• llm.base_url and llm.model — point these at your actual LLM endpoint and model name. If your endpoint requires authentication, set the LM_API_TOKEN environment variable or use llm.api_key with a secret reference like env:LM_API_TOKEN.
• network.subnet and network.host_ip — set these to your actual network. For example, 192.168.1.0/24 and 192.168.1.100.
• network.known_devices — populate this with your known devices to reduce noisy "unknown device" alerts. Each entry needs a mac, name, and optionally a type.
• agents.breach_monitor — set enabled: true, add your emails, and provide an api_key (or set HIBP_API_KEY in your environment).
• alerts.channels — configure your real alert destinations (webhook URLs, Slack webhook URLs, SMTP credentials).

The User Guide walks through every configuration option in detail.

Common Commands

# View findings, devices, and agent run history
python -m pingting findings --limit 50
python -m pingting findings --severity critical
python -m pingting devices
python -m pingting runs --limit 50

# Acknowledge or mark findings as false positive
python -m pingting ack 123
python -m pingting fp 124

# Breach monitoring
python -m pingting run breach_monitor
python -m pingting breaches --new-only

# Learning mode and baselines
python -m pingting learning start --days 7
python -m pingting learning status
python -m pingting learning observations --agent network_scanner
python -m pingting baseline review --needs-review
python -m pingting baseline approve --id 42 --reason-code known_benign
python -m pingting learning complete

# Alert channel testing
python -m pingting alerts channels
python -m pingting alerts test --severity high --title "Test Alert"
python -m pingting alerts failures --hours 24

# Reporting
python -m pingting reports summary --hours 24
python -m pingting reports compare --window-hours 24
python -m pingting reports anomaly --window-hours 24

# Maintenance
python -m pingting maintenance backup
python -m pingting maintenance prune --days 30 --dry-run
python -m pingting maintenance export-findings --format jsonl

# macOS background service
python -m pingting service install
python -m pingting service status
python -m pingting service restart
python -m pingting service uninstall

# CLI help
python -m pingting --help
python -m pingting reports --help

Configuration

The default config file lives at config/pingting.yaml. You can point PingTing at a different path with --config:

python -m pingting --config /path/to/custom.yaml status

Secrets can be referenced in config values using two patterns:

• env:VARIABLE_NAME — resolves the value from an environment variable at runtime.
• keychain:service:account — resolves the value from the macOS Keychain.
  • service/account are validated (alphanumeric plus ., _, -) and cannot start with -.

PingTing also reads a .env file in the working directory at startup (it does not overwrite variables that are already set in the environment).

See the User Guide for a complete breakdown of every config block and option.

SquirrelOps Control-Plane Integration

PingTing is currently integrated into the shared SquirrelOps operator dashboard/API via adapter-based reads:

• status snapshot from data/status.json when available
• fallback snapshot via python -m pingting status --json
• direct recent-row reads from data/pingting.db (findings, agent_runs)

Relevant control-plane endpoints:

• GET /sentry/summary
• GET /sentry/findings
• GET /sentry/runs

See CURRENT_STATE.md and squirrelops/docs/current-state.md for the full cross-repo contract.

Optional integrations are additive. PingTing runtime behavior in this repository (CLI, daemon scheduling, findings, alerts, reporting, and plugins) remains fully supported without them.

Plugin System

PingTing supports custom agents through a plugin system with intentional safety constraints:

• Plugin modules must live under plugins.* or pingting.plugins.*.
• Module hash verification (sha256) can pin each plugin file to an expected digest (strongly recommended).
• Filesystem root enforcement (plugins.enforce_module_roots) restricts where plugin files may load from (enabled by default).
• The factory function must be named build_agent.
• The factory must return a BaseAgent instance.

Current reporting/replay hardening highlights:

• Webhook/report destinations are URL-safety validated by default (SSRF protections for loopback/private/link-local targets unless explicitly allowed).
• Hostname targets are DNS-resolved asynchronously and then pinned to the resolved IP for request dispatch (with original Host/SNI preserved) to reduce DNS rebinding risk.
• DNS resolution failures are fail-closed (dns_resolution_failed) instead of allow-on-error.
• Dead-letter replay supports signed, quorum-approved manifests with per-line digest validation at execution time.
• Reporting/anomaly/dead-letter history rows support optional HMAC signing (reporting.history_signing_secret) and invalid signatures are ignored on read.
• Dead-letter replay and report-health scans use stream-based JSONL processing for large queue files.
• Reporting JSONL rotation is configurable per file class (history, dead-letter, replay-audit, proactive-audit) to control long-term disk growth.

python -m pingting plugins list
python -m pingting plugins scaffold --output plugins/my_agent.py
python -m pingting plugins validate
python -m pingting plugins run my_agent

Security Notes

• All database queries use parameterized statements (no string interpolation).
• XML parsing uses defusedxml to prevent XXE and related attacks.
• Subprocess calls use argument lists — there is no shell=True anywhere.
• Keychain secret lookups validate keychain:service:account identifiers before invoking security.
• Plugin loading is constrained to trusted namespaces and factory names.
• Plugin loading supports optional SHA256 pinning and filesystem root allowlists.
• Export commands enforce output path boundaries under maintenance.export_dir.
• LLM classification output is sanitized and validated before persistence.
• Webhook requests include explicit security headers (Content-Type, User-Agent, X-PingTing-Event) and optional HMAC signing (X-PingTing-Timestamp, X-PingTing-Nonce, X-PingTing-Signature, X-PingTing-Signature-Alg).
• URL safety checks are fail-closed on DNS errors and request dispatch uses DNS-pinned connection targets.
• Dead-letter replay execution supports signed manifests with quorum-based approval and revocation.
• Webhook signature verification helpers support fail-closed replay protection (require_replay_cache=True) and persistent nonce caches.

Do not commit .env files or config files containing plaintext secrets. Use env: or keychain: references instead.

Development

pip install -r requirements-dev.txt
pre-commit install
pre-commit run --all-files
ruff check .
mypy
pytest -q --cov=pingting --cov-report=term-missing

Container

docker build -t pingting .
docker run --rm -it \
  -v "$(pwd)/config:/app/config" \
  -v "$(pwd)/data:/app/data" \
  -v "$(pwd)/logs:/app/logs" \
  --network host \
  pingting

Repository Layout

pingting/           # Core application code
  agents/           # Built-in agent implementations
  plugins/          # Plugin framework (base class, registry)
  utils/            # Helpers (network, secrets, parsers, webhook signing)
  main.py           # CLI entry point (all commands defined here)
  orchestrator.py   # Scheduler and agent execution engine
  reporting.py      # Report generation, dead letters, replay, proactive workflows
  alert_manager.py  # Alert dispatch, retry, delivery tracking
  config.py         # Config loading, env overrides, secret resolution
  models.py         # Pydantic models for all config and data structures
  llm_client.py     # OpenAI-compatible LLM client
  db.py             # SQLite database layer
  launchd.py        # macOS launchd service management
config/             # Configuration files
data/               # SQLite database, state files, exports
logs/               # Application logs
tests/              # Test suite
plugins/            # User plugin directory

License Choice

PingTing is source-available under PolyForm Noncommercial 1.0.0.

• Allowed: personal use, research, educational use, and other noncommercial use.
• Not allowed without separate permission: commercial use, resale, paid hosting, or repackaging for commercial advantage.

If you need commercial rights, open an issue in this repository to request a separate commercial license.

License

This repository is licensed under PolyForm Noncommercial 1.0.0. See LICENSE.

Trademark Policy

Use of project names and logos is governed by TRADEMARK_POLICY.md.