Planning codebase modernization and reliability improvements

.env.example

@@ -0,0 +1,23 @@
+# OSniffy runtime configuration
+# Copy this file to `.env` and replace placeholders.
+# Never commit real credentials.
+
+# --- MySQL write path (app runtime user: INSERT/SELECT on target table) ---
+MYSQL_HOST="127.0.0.1"
+DB_NAME="OSniffy"
+TABLE_NAME="packets"
+MYSQL_USER="osniffy_ingest"
+MYSQL_PASS="replace-with-strong-password"
+
+# --- MySQL read-only path (Grafana datasource user: SELECT only) ---
+MYSQL_USER_GRAFANA="osniffy_grafana_ro"
+MYSQL_PASS_GRAFANA="replace-with-strong-password"
+
+# --- Grafana ---
+GRAFANA_HOST="127.0.0.1"
+GRAFANA_PORT=3000
+# Service account token with minimal dashboard/datasource scope
+GRAFANA_API_KEY="replace-with-service-account-token"
+
+# Optional desktop user for browser launch when app runs as root
+CLIENT="your-local-username"

.github/workflows/ci.yml

@@ -0,0 +1,132 @@
+name: CI
+
+on:
+  push:
+    branches: ["master", "main"]
+  pull_request:
+    branches: ["master", "main"]
+
+permissions:
+  contents: read
+
+# Cancel in-progress runs for the same branch so merged PRs don't waste runners.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # --------------------------------------------------------------------------
+  # Lint & static analysis
+  # --------------------------------------------------------------------------
+  lint:
+    name: Lint & Type-check
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install linting tools
+        run: pip install ruff mypy types-requests
+
+      - name: Ruff – lint
+        run: ruff check osniffy/ tests/
+
+      - name: Ruff – format check
+        run: ruff format --check osniffy/ tests/
+
+      - name: Mypy – type check
+        run: mypy osniffy/
+
+  # --------------------------------------------------------------------------
+  # Test matrix
+  # --------------------------------------------------------------------------
+  test:
+    name: Tests – Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    needs: lint
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install system dependencies
+        run: sudo apt-get install -y libpcap-dev
+
+      - name: Install package with dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests with coverage
+        run: pytest --cov=osniffy --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v5
+        with:
+          file: coverage.xml
+          fail_ci_if_error: false
+
+  # --------------------------------------------------------------------------
+  # Package build integrity check
+  # --------------------------------------------------------------------------
+  package:
+    name: Build package
+    runs-on: ubuntu-latest
+    needs: lint
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install system dependencies
+        run: sudo apt-get install -y libpcap-dev
+
+      - name: Install build tools
+        run: pip install build hatchling
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Verify package contents
+        run: |
+          pip install dist/*.whl
+          python -c "import osniffy; print(osniffy.__version__)"
+
+  # --------------------------------------------------------------------------
+  # Dependency vulnerability scan
+  # --------------------------------------------------------------------------
+  security:
+    name: Dependency vulnerability scan
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install pip-audit
+        run: pip install pip-audit
+
+      - name: Install project dependencies
+        run: |
+          sudo apt-get install -y libpcap-dev
+          pip install -e .
+
+      - name: Audit dependencies
+        run: pip-audit --progress-spinner=off

.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install system dependencies
+        run: sudo apt-get install -y libpcap-dev
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Generate checksums
+        run: sha256sum dist/* > dist/SHA256SUMS.txt
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: |
+            dist/*
+            CHANGELOG.md

.gitignore

@@ -2,6 +2,14 @@
 .env
 venv
 __pycache__
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.coverage
+coverage.xml
+dist/
+build/
+*.egg-info/
 
 # Text files
 *.txt

CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## [Unreleased]
+
+### Added
+
+- Modern Python package layout under `osniffy/` with executable CLI entrypoint.
+- Centralized project metadata and tooling in `pyproject.toml`.
+- Strong test suite for parser, config, CLI, DB repository, reader, dashboard, and sniffer behavior.
+- CI workflow with lint, format-check, type-check, tests, build verification, and dependency audit.
+- Declarative Grafana provisioning assets under `grafana/provisioning/`.
+- Root `.env.example`, `CONTRIBUTING.md`, and architecture/spec updates in `README.md`.
+
+### Changed
+
+- Import-time side effects moved into explicit startup flow.
+- Structured logging and explicit exit-code handling in CLI paths.
+- Packet persistence logic hardened with batching, retries, rollback, and filtering.
+
+### Security
+
+- Added dependency audit in CI.
+- Documented least-privilege DB user model and privileged capture requirements.

CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+## Prerequisites
+
+- Python 3.11+
+- Linux recommended for sniffer-mode development
+- `libpcap-dev` installed for `python-libpcap` builds
+
+## Local setup
+
+```bash
+cp .env.example .env
+pip install -e ".[dev]"
+```
+
+## Development workflow
+
+1. Create a feature branch.
+2. Make focused changes.
+3. Run quality gates locally.
+4. Open a pull request with a clear summary and test evidence.
+
+## Required checks
+
+```bash
+ruff check osniffy/ tests/
+ruff format --check osniffy/ tests/
+mypy osniffy/
+pytest
+```
+
+## Testing guidance
+
+- Add unit tests for parser/config/CLI/DB logic changes.
+- Keep tests deterministic; prefer fixture bytes over live traffic.
+- For integration behavior, use mocks or ephemeral infrastructure.
+
+## Security expectations
+
+- Never commit credentials, API tokens, or real `.env` files.
+- Prefer least-privilege DB roles.
+- Document any raw-socket or privileged runtime assumptions in PRs.