marker/guarddog-nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: sync documentation with latest changes (168 tests, metrics, Makefile, pre-commit)

Browse Source
This commit is contained in:
Marker689
2026-05-11 23:21:11 +03:00
parent 5c8cbabefd
commit 6ea5c85a4b
3 changed files with 71 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
AGENTS.md
View File

@@ -26,7 +26,7 @@ For local development without Docker:
make install dev
export $(cat .env | xargs)
python -m guarddog_nexus.main
make test # 137 tests (101 unit + 36 e2e)
make test # 168 tests
make lint # ruff
make format # ruff format + fix
```
@@ -70,7 +70,7 @@ guarddog_nexus/
3. `harvester.py` downloads file (async via `asyncio.to_thread`), validates URL against `NEXUS_ALLOWED_HOSTS` (SSRF protection), computes SHA256, deduplicates
4. `scanner.py` runs `guarddog <ecosystem> scan <file> --output-format json`
5. Findings stored in SQLite (`scans` + `findings` tables)
6. If `LLM_ENABLED=1` and `LLM_AUTO_ANALYZE=1`, `llm.py` sends findings to the configured model in parallel via `asyncio.gather` (respects `LLM_MAX_CONCURRENT_ANALYSES`). Retry logic with exponential backoff (2s, 4s, 8s, max 3 attempts). `finding.report` state machine: `None` → `{"status": "analyzing"}` → `{verdict, summary, analysis, severity_rating}` or `None` on failure. LLM response validated via `_validate_report()` which applies defaults for missing fields (`verdict→unknown`, `severity_rating→unknown`, etc.).
6. If `LLM_ENABLED=1` and `LLM_AUTO_ANALYZE=1`, `llm.py` sends findings to the configured model in parallel via `asyncio.gather` (respects `LLM_MAX_CONCURRENT_ANALYSES`). Retry logic with exponential backoff (2s, 4s, 8s, max 3 attempts). `finding.report` state machine: `None` → `{"status": "analyzing"}` → `{verdict, summary, analysis, severity_rating}` or `None` on failure. LLM response validated via `_validate_report()` which applies defaults for missing fields (`verdict→unknown`, `severity_rating→unknown`, etc.). Progress tracked via Prometheus counters: `guarddog_llm_analyzed_total` and `guarddog_llm_pending_total`.
---
@@ -81,11 +81,14 @@ guarddog_nexus/
- **Line length:** 100 (ruff)
- **Lint:** `ruff check guarddog_nexus tests` (E/F/I/W rules)
- **Format:** `ruff format guarddog_nexus tests`
- **Tests:** `pytest -v` (137 tests: 101 unit + 36 e2e, pytest-asyncio auto mode)
- **Tests:** `pytest -v` (168 tests, pytest-asyncio auto mode)
- **Commits:** Russian descriptions, prefix convention: `feat:`, `fix:`, `refactor:`, `docs:`, `ui:`
- **No comments** in code unless explicitly requested
- **Async I/O:** file reads/writes wrapped in `asyncio.to_thread()` — never raw `open()` in async context
- **Config validation:** `_env_int` logs a warning on invalid values instead of crashing
- **Type checking:** `make typecheck` runs `mypy guarddog_nexus` (strict mode)
- **Pre-commit:** `.pre-commit-config.yaml` with ruff, ruff-format, trailing-whitespace, end-of-file-fixer, check-yaml, check-toml, check-added-large-files, detect-private-key
- **CSV export:** `_csv_safe()` in `api_scans.py` prepends `'` to values starting with `=`, `+`, `-`, `@` — blocks formula injection when opening CSV in spreadsheet apps
---
@@ -171,7 +174,35 @@ docker compose down -v # stop + destroy volumes (make docker-destroy)
docker compose logs -f # tail logs
```
The Dockerfile uses `uv pip install . --system` to install the package and all dependencies from `pyproject.toml`. GuardDog is installed as a separate `uv pip install --system "guarddog>=2.10.0"` step. A `.dockerignore` excludes cache dirs, tests, and examples. Docker HEALTHCHECK at `/health` runs every 30 seconds.
The Dockerfile uses `uv pip install . --system` to install the package and all dependencies from `pyproject.toml`. GuardDog is installed as a separate `uv pip install --system "guarddog>=2.10.0"` step. Dependencies are installed before source code COPY for efficient layer caching. A `.dockerignore` excludes cache dirs, tests, and examples. Docker HEALTHCHECK at `/health` runs every 30 seconds.
Logging driver configured as `json-file` with rotation (max-size: 10m, max-file: 3) for both `guarddog-nexus` and `nexus` services. Nexus service also has a HEALTHCHECK (`curl` to `/service/rest/v1/status`).
---
## Makefile targets
| Command | Description |
|---------|-------------|
| `make install` | Install project dependencies |
| `make dev` | Install dev dependencies |
| `make test` | Run pytest -v |
| `make lint` | Ruff check |
| `make format` | Ruff format + fix |
| `make typecheck` | mypy strict mode |
| `make check` | lint + format + typecheck + test |
| `make run` | Start the app via `python -m guarddog_nexus.main` |
| `make setup-env` | Copy `.env.example` → `.env` if missing |
| `make docker-build` | Build Docker image |
| `make docker-up` | Build + start stack (`up -d --build`) |
| `make docker-down` | Stop stack |
| `make docker-destroy` | Stop + destroy volumes (`-v`) |
| `make docker-rebuild` | Down + up --build |
| `make docker-logs` | Tail logs |
| `make docker-ps` | `docker compose ps` |
| `make docker-shell` | Exec bash in guarddog-nexus container |
| `make docker-restart` | Restart guarddog-nexus service |
| `make clean` | Remove build artifacts |
---
@@ -181,7 +212,7 @@ The Dockerfile uses `uv pip install . --system` to install the package and all d
- Tests use in-memory SQLite (`:memory:`)
- `conftest.py` sets up `os.environ` before importing the app
- Mock `guarddog` output via fixtures — no real CLI execution
- 137 tests covering: API, webhooks, harvester, scanner, web UI, i18n, metrics, LLM analysis, e2e flows
- 168 tests covering: API, webhooks, harvester, scanner, web UI, i18n, metrics, LLM analysis, config, schemas, engine, e2e flows
- E2E tests in `tests/e2e/` cover full webhook-to-scan pipeline, API filtering/pagination, LLM analysis, and error handling
When adding features: