Backend phase 1

[jcobosmeta]

No description provided.

[Copilot]

Pull request overview

Implements the AgentHound Backend “Fase 1 / MVP” as a new FastAPI service that ingests YAML architectures, normalizes into an IR + NetworkX graph, runs initial FH rules, and exposes read endpoints with a spec-style error envelope.

Changes:

• Add core pipeline: YAML loading + adapter dispatch (generic), IR normalization/validation, graph build + traversal, rule engine (FH-001/002/003/006) with scoring and finding registry.
• Add FastAPI app with /health, POST /analyses, and graph/findings read endpoints; persist analysis results in-memory and mirrored to disk as JSON.
• Add developer enablement: docs (API/IR/rules), Dockerfile, pyproject, and a pytest suite with fixtures.

Reviewed changes

Copilot reviewed 50 out of 59 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
README.md	Updates repo status/layout to reflect Backend Fase 1 being implemented and points to backend docs.
Backend/pyproject.toml	Defines backend package metadata, dependencies, and pytest config.
Backend/Dockerfile	Adds a container build for running the FastAPI service.
Backend/.gitignore	Ignores venv/data/cache artifacts for the backend.
Backend/.dockerignore	Excludes prototype/tests and most markdown from Docker build context (keeps app/docs/README).
Backend/app/init.py	Introduces backend package version.
Backend/app/main.py	Creates FastAPI app, routers, exception handlers, and CORS middleware.
Backend/app/logging_util.py	Adds structured JSON event logging utilities.
Backend/app/docs/README.md	Adds run/test instructions and module map for the backend MVP.
Backend/app/docs/api.md	Documents the Fase 1 HTTP API contract and error envelope.
Backend/app/docs/ir_and_rules.md	Documents IR schema, catalogs, rules, and scoring model.
Backend/app/docs/glossary.md	Adds glossary for key backend concepts.
Backend/app/docs/decisions.md	Records architectural decisions and deferred scope for later phases.
Backend/app/api/errors.py	Implements spec-style error envelope and exception handlers.
Backend/app/api/routes/analyze.py	Implements POST /analyses endpoint.
Backend/app/api/routes/graphs.py	Implements GET /analyses/{id}/graph endpoint.
Backend/app/api/routes/findings.py	Implements GET /analyses/{id}/findings and GET /analyses/{id}/findings/{finding_id}.
Backend/app/core/catalogs.py	Adds cached YAML catalog loaders (capabilities, defaults, rules).
Backend/app/core/pipeline.py	Implements end-to-end analysis orchestration and persistence.
Backend/app/core/parser/yaml_loader.py	Adds YAML parsing + framework detection heuristic.
Backend/app/core/parser/adapters/init.py	Adds adapter dispatch and wraps unimplemented adapters into IRValidationError.
Backend/app/core/parser/adapters/generic_adapter.py	Implements generic YAML → IR adapter.
Backend/app/core/parser/adapters/crewai_adapter.py	Adds Fase 3 stub adapter.
Backend/app/core/parser/adapters/dify_adapter.py	Adds Fase 3 stub adapter.
Backend/app/core/parser/adapters/langgraph_adapter.py	Adds Fase 3 stub adapter.
Backend/app/core/ir/models.py	Adds Pydantic v2 models for IR, findings, summaries, and error envelope.
Backend/app/core/ir/normalizer.py	Applies safe defaults and defines tool→capability mapping helpers.
Backend/app/core/ir/validators.py	Adds IR + finding validation routines raising IRValidationError.
Backend/app/core/graph/builder.py	Builds a NetworkX MultiDiGraph from the IR.
Backend/app/core/graph/traversal.py	Adds graph traversal/selectors and path utilities for rules.
Backend/app/core/graph/serializer.py	Serializes IR+findings into the frontend graph shape.
Backend/app/core/rules/scoring.py	Implements additive risk scoring and severity banding.
Backend/app/core/rules/registry.py	Loads rule metadata and assembles Finding objects.
Backend/app/core/rules/path_rules.py	Implements FH path-based rules (FH-001/003/006).
Backend/app/core/rules/node_rules.py	Implements FH node/reachability rule (FH-002).
Backend/app/core/rules/engine.py	Orchestrates rule execution, sorts findings, assigns stable ids.
Backend/app/core/storage/repository.py	Adds in-memory + JSON-on-disk persistence repository.
Backend/app/core/controls/.gitkeep	Placeholder for future Fase 2 controls modules.
Backend/app/catalogs/capabilities.yaml	Adds capability verb catalog used for validation and rules.
Backend/app/catalogs/node_properties.yaml	Adds safe defaults and enumerations for node properties.
Backend/app/catalogs/rules.yaml	Adds Fase 1 rule descriptors (metadata/control mappings).
Backend/tests/conftest.py	Sets test data dir and provides fixture-loading helpers.
Backend/tests/test_api.py	Adds API-level tests for health/analyze/graph/findings and error envelopes.
Backend/tests/test_generic_adapter.py	Adds tests for generic adapter + normalizer defaults and error handling.
Backend/tests/test_graph_traversal.py	Adds tests for traversal selectors/paths/capabilities/reachability.
Backend/tests/test_ir_validators.py	Adds tests for IR validation errors (empty, dup ids, dangling edges, unknown cap).
Backend/tests/test_rules_engine.py	Adds tests for rule triggering, sorting, and “safe” architecture behavior.
Backend/tests/test_scoring.py	Adds scoring and severity-band tests.
Backend/tests/fixtures/hiresmart_generic.yaml	Adds representative exfiltration fixture.
Backend/tests/fixtures/hiresmart_fetchweb.yaml	Adds indirect-injection fixture for FH-006.
Backend/tests/init.py	Marks tests as a package.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 51 out of 60 changed files in this pull request and generated 8 comments.

[Copilot]

Pull request overview

Copilot reviewed 52 out of 61 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 52 out of 61 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 52 out of 61 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 53 out of 62 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 53 out of 62 changed files in this pull request and generated 5 comments.