SecWatch

SecWatch is an on-host security screening agent that monitors web server logs, detects suspicious activity, and enforces containment actions such as IP bans while archiving incidents for later forensics.

• PROJECT STATUS: DEVELOPMENT / NOT PRODUCTION-READY
• SecWatch is an experimental on-host security agent.
• It has not undergone extensive real-world testing and may cause
• unintended disruptions (e.g. self-bans) if misconfigured.
• Do not deploy on production systems without careful review.

Features

• Real-time parsing of web access logs with rotation awareness.
• Pluggable detection rules (regex-based and status burst detection).
• Incident storage in JSON for easy ingestion into central systems.
• Notification helpers for email, Slack (Block Kit with severity colour coding + ack/escalate buttons—links currently placeholders), or generic webhooks.
• Severity-tagged alerts for faster triage and prioritisation.
• Optional automated containment via configurable ban/unban commands.

Quick Start

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
python -m pip install -e .[dev,web]
python -m pytest                  # Optional: python -m flake8 src tests

Copy config/secwatch.yaml.example to your desired location, adjust the log paths, alert channels, and ban command helpers, then run:

secwatch run --config path/to/secwatch.yaml

Browse incidents from the CLI:

secwatch incidents list --directory /var/security_incidents --severity high --since 2025-11-01T00:00:00

Or launch the web dashboard (requires [web] extras):

secwatch dashboard --directory /var/security_incidents --host 0.0.0.0 --port 8000

Project Layout

• src/secwatch/: Agent implementation (tailer, parser, detectors, actions, notifier, CLI).
• config/: Sample configuration files and detector library.
• tests/: Pytest-based unit tests and fixtures.

CLI Usage

• Start the agent: secwatch run --config path\to\secwatch.yaml (default when no subcommand is provided).
• Inspect incidents directory: secwatch incidents list --directory C:\path\to\incidents.
• Filter examples:
  • secwatch incidents list --severity high --since 2025-11-01T00:00:00
  • secwatch incidents list --format json --directory /var/security_incidents
• View a specific incident (JSON): secwatch incidents show INCIDENT_ID --directory C:\path\to\incidents --format json.
• Launch web dashboard (requires pip install secwatch[web]): secwatch dashboard --host 0.0.0.0 --port 8000 --directory /var/security_incidents.

Local Development

• Install development dependencies: python -m pip install -e .[dev]
• Run tests: python -m pytest
• Run linting: flake8 src

Packaging

SecWatch is distributed as a standard Python package. The secwatch console script is declared in pyproject.toml, enabling python -m pip install . to expose the CLI.

• Docker image: packaging/build_docker.sh builds an image tagged with the current version.
• Debian package: packaging/build_deb.sh prepares .deb artifacts (requires Debian packaging toolchain).
• See docs/packaging.md and the full docs/install.md guide for detailed instructions and release checklist.

Roadmap Highlights

• Incident dashboard to visualise recent activity and drill into stored incidents.
• Slack ack/escalate buttons wired to automation endpoints (ticketing/paging).
• Release automation: CI builds & publishes Docker + Debian artifacts on tags.
• Packaging polish for publishing to internal registries/repositories.

More details: docs/roadmap.md. (Prometheus/telemetry integration intentionally deferred.)

---

Additional Documentation

• docs/install.md – Full installation guide (source, Docker, Debian).
• docs/deploy.md – Operational deployment checklist.
• docs/incident_playbook.md – On-call / incident response workflow.
• docs/packaging.md – Packaging pipeline and release process.
• docs/architecture.md – High-level design overview.