# Iotspy Context

> IoTSpy project context — architecture, conventions, and security caveats specific to this codebase. Use when working in the IoTSpy repo, especially alongside dotnet-engineer, security-code-review, or threat-modeling. Pointers into in-repo docs rather than duplicated facts that rot.

- Skill: `aarnold-livefront/iotspy-context` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aarnold-livefront/iotspy-context`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aarnold-livefront/iotspy-context/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: aarnold-livefront (https://skillmd.com/u/aarnold-livefront)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aarnold-livefront/iotspy-context

---


# IoTSpy Context

This skill holds only the IoTSpy-specific bits that matter when reasoning about the codebase. Generic .NET, security-review, and threat-modeling guidance live in their own skills. **Don't duplicate facts here that already live in CLAUDE.md or AGENT.md** — point to them and let them be the source of truth.

## Where to look first

- **`CLAUDE.md`** — quick commands, project structure, current state (test counts, migration count, completed phases). This is the canonical place for "how big is the project right now."
- **`AGENT.md`** — full technical reference: commands, architecture, naming conventions, testing guidance, known operational requirements (setcap, JSON enum serialization, iOS cert constraints, SQLite migration foot-guns).
- **`docs/ARCHITECTURE.md`** — detailed architecture spec.
- **`docs/CODE-PATTERNS.md`** — implementation patterns to follow when adding controllers, repositories, hubs, decoders.
- **`docs/PHASES-COMPLETED.md`** / **`docs/PHASES-ROADMAP.md`** — phase history and roadmap.
- **`docs/TROUBLESHOOTING.md`** — known issues and resolutions.

When asked "what's the current state" / "how many tests" / "which migration is latest" / "what phase are we on", **read `CLAUDE.md` rather than answering from memory**. State drifts.

## Architectural shape (stable enough to state)

The project layout is stable, even when counts change:

- **`IoTSpy.Api`** — ASP.NET Core host, REST controllers, SignalR hubs, middleware
- **`IoTSpy.Core`** — domain models, interfaces, enums; **must not** take infrastructure dependencies
- **`IoTSpy.Storage`** — EF Core DbContext + repositories (SQLite/Postgres)
- **`IoTSpy.Proxy`** — TLS MITM/passthrough, SSL stripping, WebSocket/MQTT/CoAP proxies
- **`IoTSpy.Protocols`** — MQTT, DNS, CoAP, WebSocket, gRPC, Modbus, OpenRTB, telemetry decoders
- **`IoTSpy.Scanner`** — port scan, fingerprinting, CVE lookup, packet capture
- **`IoTSpy.Manipulation`** — rules engine, scripted breakpoints, replay, fuzzer, AI mock, OpenRTB PII, API spec generation, content replacement
- **`IoTSpy.*.Tests`** — unit + integration tests
- **`frontend/`** — Vite 6 + React 19 + TypeScript dashboard

Namespace prefix is `IoTSpy` (capital I, o, T, S). Docker image/container name is `iotspy`.

## Conventions that matter

- **Run `dotnet test` before committing.** All backend tests must stay green.
- **New backend logic needs a test.** Use NSubstitute for mocks; EF Core SQLite in-memory for repository tests.
- **New EF entities need a migration** (`dotnet ef migrations add <Name> --project src/IoTSpy.Storage --startup-project src/IoTSpy.Api`).
- **Hosted + singleton services** use `AddHostedService(sp => sp.GetRequiredService<T>())` — never double-register.
- **JSON enum serialization** must be configured on **both** `AddControllers().AddJsonOptions(...)` *and* `AddSignalR().AddJsonProtocol(...)`. Missing the SignalR call sends numeric enum values over live captures and crashes the frontend timeline.
- **Polly resilience** uses two named pipelines: `iotspy-connect` (timeout → retry → circuit breaker, keyed per upstream host) and `iotspy-tls` (timeout only).

## Security caveats specific to IoTSpy

When reviewing code or threat-modeling for this codebase, these are the IoTSpy-specific surfaces a generic skill won't catch:

1. **Dual-use research tool.** IoTSpy *intentionally* MITMs TLS, strips SSL, scans ports, captures packets, and rewrites traffic. Things that would be malicious in another context are core features here. Do not flag these as bugs — call them out as design decisions when the surrounding context shifts (e.g., if the proxy accepts connections from outside a research lab, the threat model changes).

2. **Single-user JWT, BCrypt password in `ProxySettings` row (Id=1).** The whole product authenticates against one row. Anything weakening that row's hash, leaking it, or bypassing the `Auth__JwtSecret` ≥ 32-char guard is critical. Verify the secret-length enforcement is reachable on every entry point (controllers, SignalR, design-time DbContext factory).

3. **SignalR token via `?access_token=` query param.** This means tokens can land in proxy/access logs. Reviewing logging or middleware that sees URLs needs to consider redaction.

4. **Roslyn (C#) and Jint (JS) scripted breakpoints.** Anywhere user-supplied scripts execute is RCE-by-design. Confirm it stays gated behind admin auth, that scripts cannot escape into the host process beyond the documented surface, and that imports/timeouts are bounded. Flag any change that broadens the script API.

5. **SharpPcap `CAP_NET_RAW` / `CAP_NET_ADMIN`.** The API process gets raw socket access via `setcap`. Any new code path that handles arbitrary sockets or executes privileged operations should be audited against this elevated capability.

6. **TLS validation intentionally disabled upstream in the proxy.** Don't spread that pattern outside the proxy. Other components (telemetry, AI mock client, scanner) must validate TLS normally.

7. **Captured-data confidentiality.** The product's value is intercepted traffic — credentials, tokens, payloads. Storage encryption-at-rest, retention, and access control on captures, replays, and exports are core, not nice-to-have.

8. **Migration foot-gun on SQLite.** `AlterColumn` emits `PRAGMA foreign_keys = 0` which can't run inside the EF transaction wrapper. Use `migrationBuilder.Sql(...)` directly. See `AGENT.md` § "EF Core migrations on SQLite" for the worked example.

9. **iOS/macOS leaf cert constraints.** ≤397-day validity, AKI keyid-only, IP-as-`GeneralName.IPAddress`. If you regenerate the root CA, delete leaf certs from the database. See `AGENT.md` for the SQL.

## When to use this skill alongside others

- With **`dotnet-engineer`**: when designing a new controller, hub, repository, or background service in this repo. Apply IoTSpy conventions on top of generic .NET advice.
- With **`security-code-review`**: when reviewing IoTSpy code, layer the IoTSpy-specific risks above onto the generic 7-step checklist.
- With **`threat-modeling`**: when modeling new IoTSpy features, anchor "dual-use tool" considerations from this skill into the model.

When in doubt about a project-specific fact, **read `CLAUDE.md` and `AGENT.md`**. Don't paraphrase from memory.