Build AutoShield secure AWS IoT telemetry MVP

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: Python tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python 3.13 test suite
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+          cache: pip
+
+      - name: Install project
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run automated tests
+        run: python -m pytest -q

.gitignore

@@ -25,3 +25,5 @@ data/*
 .DS_Store
 Thumbs.db
 
+# Python package metadata
+*.egg-info/

README.md

@@ -1,27 +1,242 @@
 # AutoShield Lab
 
-AutoShield Lab is an original, local learning project for monitoring synthetic
-connected-vehicle security events and supporting incident response.
+**A security-first connected-vehicle telemetry proof of concept built with Python, SQLite, AWS IoT Core, MQTT 5, mutual TLS, and infrastructure as code.**
 
-The core platform will be developed incrementally. It will not depend on a 3D
-vehicle simulator, connect to real vehicles, or target external systems.
+AutoShield Lab demonstrates how a fictional connected vehicle can produce validated telemetry, be checked against an authorised vehicle registry, trigger explainable security rules, and publish a tightly controlled message to AWS IoT Core.
 
-## Current status
+The project was designed as a Solutions Architecture portfolio case study. It focuses on requirements, trust boundaries, least-privilege access, cost control, testability, and documented architectural decisions rather than on a generic CRUD application.
 
-Milestone 0 — Foundation is in progress. The repository currently contains only
-the initial project structure and documentation; no application features have
-been implemented.
+> All vehicles, events, credentials, and scenarios used by the application are fictional or synthetic. AutoShield Lab never connects to a real vehicle or external target.
+
+## What the MVP proves
+
+- A versioned telemetry contract rejects malformed or unsafe input.
+- A local SQLite registry authorises only known vehicles with an active lifecycle status.
+- Explainable detection rules identify authentication bursts and high battery temperature.
+- Unknown or inactive vehicle identities are rejected before processing.
+- A dedicated publishing boundary prevents vehicle and MQTT-topic mismatches.
+- One fictional device authenticates to AWS IoT Core using an X.509 certificate and mutual TLS.
+- Its IoT policy permits only the approved MQTT client ID and telemetry topic.
+- Cloud publishing uses MQTT 5 with QoS 1 and a dynamically discovered regional endpoint.
+- Infrastructure is reproducible through AWS CloudFormation.
+- The automated suite completes with **28 tests and 4 subtests passing**.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    S["Synthetic vehicle scenario"] --> V["Telemetry contract validation"]
+
+    V --> A["Vehicle registry authorisation"]
+    R[("SQLite vehicle registry")] --> A
+    A --> D["Explainable detection rules"]
+    D --> I["Local incident results"]
+
+    V --> P["Cloud publish authorisation"]
+    P --> M["MQTT 5 / mTLS / QoS 1"]
+    C["X.509 device certificate"] --> M
+    M --> AWS["AWS IoT Core - eu-west-2"]
+    CF["CloudFormation: Thing + least-privilege policy"] --> AWS
+    AWS --> T["AWS MQTT test client"]
+```
+
+The local security pipeline and cloud publishing proof share the same validated telemetry model. Detection remains local in this MVP; the AWS portion proves secure device identity, topic-level authorisation, and encrypted transport without adding databases, queues, or continuously running compute.
+
+## Security model
+
+| Control | Implementation | Architectural purpose |
+| --- | --- | --- |
+| Input trust boundary | Strict `TelemetryEvent` validation | Reject malformed data before business processing |
+| Vehicle authorisation | SQLite registry and lifecycle status | Prevent unknown, maintenance, or retired identities from being processed |
+| Explainable detection | Deterministic rules with severity and evidence | Produce findings that an operator can understand and test |
+| Publish authorisation | Vehicle ID, Thing name, client ID, and topic checks | Prevent confused-deputy and topic-substitution mistakes |
+| Device authentication | One X.509 certificate attached to one fictional Thing | Give the demonstration vehicle a distinct machine identity |
+| Least privilege | Exact `iot:Connect` and `iot:Publish` resource ARNs | Permit only the intended client ID and telemetry topic |
+| Transport security | MQTT 5 over mutual TLS | Encrypt traffic and authenticate both sides of the connection |
+| Secret handling | Certificates and keys stored under Git-ignored `data/` | Keep private key material out of source control |
+| Cost boundary | One Thing, one policy, one certificate, manual one-message demo | Avoid continuously running or unnecessary cloud resources |
+
+The IoT policy intentionally does **not** grant subscribe, receive, wildcard publish, fleet-wide access, or administrative actions.
+
+## End-to-end scenarios
+
+The repeatable local demonstration covers three outcomes:
+
+1. **Normal telemetry** - accepted with no incident.
+2. **Suspicious telemetry** - accepted and evaluated into two explainable incidents:
+   - authentication failure burst;
+   - high battery temperature.
+3. **Identity impersonation** - rejected because the claimed vehicle is not registered.
+
+The cloud demonstration publishes one validated synthetic event to:
+
+```text
+autoshield/vehicles/autoshield-demo-vehicle-001/telemetry
+```
+
+The client certificate cannot connect using a different client ID or publish to a different topic.
+
+## Cloud proof
+
+### Message received by AWS IoT Core
+
+![Synthetic telemetry received in the AWS IoT MQTT test client](docs/assets/autoshield-aws-iot-console-redacted.png)
+
+### Authorisation and QoS 1 publish receipt
+
+![AWS IoT authorisation and successful AutoShield publish receipt](docs/assets/autoshield-cloud-publish-terminal-redacted.png)
+
+Account identifiers and local usernames are redacted. No endpoint, access token, certificate, or private key is included in these images.
+
+## Technology choices
+
+- **Python 3.13** - domain logic, validation, detection, orchestration, and demos
+- **SQLite** - zero-cost local vehicle registry with database constraints
+- **pytest and unittest** - automated behaviour and transport-boundary testing
+- **AWS IoT Device SDK v2** - MQTT 5 mutual-TLS connectivity
+- **AWS IoT Core** - managed device gateway and policy enforcement
+- **AWS CloudFormation** - reproducible IoT Thing and policy configuration
+- **Git** - milestone-based development and architectural history
+
+## Run locally
+
+### Prerequisites
+
+- Python 3.13 or later
+- Git
+
+PowerShell example:
+
+```powershell
+git clone https://github.com/arshhunerkar-security/AutoShield-Lab.git
+cd AutoShield-Lab
+python -m venv .venv
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
+.\.venv\Scripts\Activate.ps1
+python -m pip install -e ".[dev]"
+```
+
+Run the automated suite:
+
+```powershell
+python -m pytest -q
+```
+
+Run the local security demonstration:
+
+```powershell
+python -m autoshield_lab.demo
+```
+
+The local demonstration is repeatable and requires no AWS account.
+
+## Optional AWS IoT proof
+
+The cloud proof is deliberately optional. The core application and tests work entirely locally.
+
+Before using it:
+
+1. Review [`infra/README.md`](infra/README.md) and the cost-control ADR.
+2. Use an IAM identity rather than the AWS root user.
+3. Deploy only the provided CloudFormation stack in the intended Region.
+4. Create a dedicated demonstration certificate and keep its private key under `data/`.
+5. Subscribe the AWS MQTT test client to the exact AutoShield telemetry topic.
+6. Run the cloud demo once, capture the result, and clean up the AWS resources when finished.
+
+Example after secure local certificate setup:
+
+```powershell
+$autoShieldEndpoint = (aws iot describe-endpoint `
+    --endpoint-type iot:Data-ATS `
+    --query "endpointAddress" `
+    --output text `
+    --region eu-west-2 `
+    --profile autoshield-admin).Trim()
+
+python -m autoshield_lab.cloud_demo --endpoint $autoShieldEndpoint
+```
+
+Never commit certificate files, private keys, cached AWS credentials, account identifiers, or endpoint values.
 
 ## Project structure
 
-- `src/autoshield_lab/` — application package
-- `tests/` — automated tests
-- `data/` — local generated data (ignored by Git except for its placeholder)
-- `docs/` — clean-room rules and learning records
+```text
+AutoShield-Lab/
+|-- docs/
+|   |-- adr/                         # Architecture decision records
+|   |-- assets/                      # Redacted portfolio evidence
+|   |-- CLEAN_ROOM.md                # Synthetic-data safety boundary
+|   |-- DETECTION_RULES.md           # Rule definitions and thresholds
+|   `-- TELEMETRY_CONTRACT.md        # Event schema and validation contract
+|-- infra/
+|   |-- iot-core.yaml                # Cost-controlled IoT infrastructure
+|   `-- README.md                    # Deployment and cleanup guidance
+|-- src/autoshield_lab/
+|   |-- cloud_demo.py                # One-message cloud demonstration
+|   |-- cloud_publisher.py           # Publishing authorisation boundary
+|   |-- database.py                  # SQLite initialisation
+|   |-- demo.py                      # Repeatable local scenarios
+|   |-- detection.py                 # Explainable security rules
+|   |-- mqtt_transport.py            # MQTT 5 mutual-TLS transport
+|   |-- pipeline.py                  # Authorised processing pipeline
+|   `-- telemetry.py                 # Validated telemetry domain model
+|-- tests/                           # Local and mocked transport tests
+`-- pyproject.toml                   # Package and test configuration
+```
+
+## Architectural decisions
+
+- [`ADR-001: Vehicle-status authorisation`](docs/adr/ADR-001-vehicle-status-authorization.md) explains why registry status is enforced before detection.
+- [`ADR-002: Free-plan cost guardrails`](docs/adr/ADR-002-free-plan-cost-guardrails.md) records the intentionally small AWS footprint and excluded services.
+- [`TELEMETRY_CONTRACT.md`](docs/TELEMETRY_CONTRACT.md) defines the accepted event boundary.
+- [`DETECTION_RULES.md`](docs/DETECTION_RULES.md) documents thresholds, severity, and rule behaviour.
+
+## Testing strategy
+
+The automated tests cover:
+
+- database constraints and repeatable initialisation;
+- telemetry validation and serialisation;
+- known, unknown, active, maintenance, and retired vehicle states;
+- detection thresholds and multi-incident events;
+- pipeline acceptance and rejection outcomes;
+- publish-topic and identity authorisation;
+- MQTT configuration, success, failure, and cleanup paths;
+- local and cloud-demo orchestration.
+
+Cloud transport tests use controlled fakes, so `pytest` does not create AWS traffic or require credentials. The screenshots document the separate manual end-to-end proof.
+
+## Design trade-offs
+
+- **SQLite instead of a managed database:** sufficient for deterministic local learning and zero-cost testing; not intended for fleet-scale concurrency.
+- **Deterministic rules instead of machine learning:** easier to explain, verify, and audit for an MVP.
+- **One certificate and one Thing:** demonstrates device identity and least privilege while limiting cost and operational risk.
+- **No cloud persistence or compute:** avoids claiming an ingestion platform that the MVP does not implement and prevents idle resources.
+- **Manual certificate lifecycle:** acceptable for one demonstration device; production fleets require automated provisioning, rotation, revocation, and audit processes.
+
+## Current limitations
+
+AutoShield Lab is a portfolio proof of concept, not a production vehicle-security product. It does not currently provide:
+
+- real-vehicle or CAN-bus integration;
+- cloud-side storage, stream processing, dashboards, or alert delivery;
+- automated certificate provisioning and rotation;
+- multi-account or multi-Region resilience;
+- production observability, SLOs, or incident-management integrations;
+- a formal automotive safety or cybersecurity certification.
+
+These boundaries are deliberate and keep the repository safe, reproducible, and honest about its scope.
+
+## Roadmap
+
+- Add a threat model and data-flow diagram.
+- Add CI for automated tests and secret scanning.
+- Introduce pluggable local persistence for incidents.
+- Design a cost-estimated cloud ingestion option using managed, event-driven services.
+- Define certificate provisioning, rotation, revocation, and fleet onboarding workflows.
+- Add operational metrics, alarms, retention requirements, and recovery objectives.
 
-## Safety boundary
+## Clean-room boundary
 
-All vehicles, electronic control units (ECUs), messages, and telemetry used by
-this project must be fictional and synthetic. See `docs/CLEAN_ROOM.md` for the
-full project rules.
+All vehicles, electronic control units, messages, events, and telemetry in this repository must remain fictional and synthetic. See [`docs/CLEAN_ROOM.md`](docs/CLEAN_ROOM.md) for the complete rules.
 

docs/DETECTION_RULES.md

@@ -0,0 +1,31 @@
+# AutoShield Detection Rules
+
+## Purpose
+
+AutoShield evaluates validated synthetic telemetry and produces zero or more
+explainable incidents.
+
+These thresholds exist only for a portfolio demonstration. They are not
+automotive safety recommendations and must not be applied to real vehicles.
+
+## Rules
+
+| Rule ID | Condition | Severity | Purpose |
+|---|---|---|---|
+| `AUTH_FAILURE_BURST` | `failed_auth_attempts_5m >= 5` | High | Identify repeated authentication failures that could indicate attempted unauthorized access |
+| `BATTERY_TEMPERATURE_HIGH` | `battery_temperature_c >= 60` | Critical | Demonstrate a critical operational anomaly requiring immediate investigation |
+
+## Processing order
+
+Telemetry must pass contract validation before it reaches the detection engine.
+A correctly formatted event can still produce an incident.
+
+Every rule is evaluated independently. Therefore, one telemetry event can
+produce multiple incidents.
+
+## Idempotency
+
+Each incident ID uses the following format:
+
+```text
+<source-event-id>:<rule-id>

docs/TELEMETRY_CONTRACT.md

@@ -0,0 +1,24 @@
+# AutoShield Telemetry Contract
+
+## Version
+
+The current telemetry schema version is `1.0`.
+
+## Purpose
+
+This contract defines the synthetic vehicle telemetry accepted by AutoShield
+Lab. It contains no real vehicle, driver, customer, VIN, or location data.
+
+## Example event
+
+```json
+{
+  "schema_version": "1.0",
+  "event_id": "evt-20260807-0001",
+  "vehicle_id": "veh-demo-001",
+  "recorded_at": "2026-08-07T09:30:00Z",
+  "speed_kph": 42.0,
+  "battery_temperature_c": 38.5,
+  "failed_auth_attempts_5m": 0,
+  "firmware_version": "3.2.1"
+}