mirror of
https://github.com/sameerk27/vigil365.git
synced 2026-07-02 10:39:35 +02:00
Samir KhanandClaude Sonnet 4.6
74a3efaf91
- SECURITY.md: disclosure policy, design/deployment model, current controls, hardening-in-progress, operator responsibilities (keeps Graph API stability notes) - docs/THREAT_MODEL.md: assets, trust boundaries, data flows, STRIDE mitigations Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
92 lines
4.5 KiB
Markdown
92 lines
4.5 KiB
Markdown
# Security & API Status
|
|
|
|
## Reporting a Security Vulnerability
|
|
|
|
If you find a security issue (e.g. credentials being logged, an endpoint leaking data), please **do not open a public issue**. Open a [GitHub Security Advisory](https://github.com/sameerk27/vigil365/security/advisories/new) instead so it can be fixed before public disclosure.
|
|
|
|
Please include the affected version/commit, reproduction steps, and potential impact. We aim to acknowledge reports within a few business days and ask for reasonable time to remediate before public disclosure.
|
|
|
|
---
|
|
|
|
## Supported Versions
|
|
|
|
Actively developed; security fixes target the latest `master`. Pin to a released commit for production and review changes before upgrading.
|
|
|
|
---
|
|
|
|
## Design & Deployment Model
|
|
|
|
Vigil365 is a **self-hosted, single-tenant** application meant to run on infrastructure the operating organisation controls — **not** a public multi-tenant SaaS.
|
|
|
|
- **Read-only against your tenant** — Graph access is app-only (client credentials) with `*.Read.All` permissions only; the app never writes to the M365 tenant.
|
|
- **Data stays in-tenant** — collected data is stored in the operator's own SQL database; nothing is sent to any third-party service.
|
|
- **Network isolation is a primary control** — designed to sit on a private network / behind a reverse proxy, not exposed directly to the internet.
|
|
|
|
---
|
|
|
|
## Current Security Controls
|
|
|
|
- **Secrets encrypted at rest** — SMTP password, webhook URLs, and the Graph client secret are DPAPI-encrypted; secrets are never returned by the API.
|
|
- **Database transport encryption** — SQL connections use `Encrypt=True`.
|
|
- **TLS in production** — HSTS + HTTPS redirection enforced outside Development; TLS via reverse proxy or Kestrel certificate (see README "HTTPS / TLS").
|
|
- **Safe error handling** — API errors return generic messages; detail goes to server logs only.
|
|
- **Security headers** — `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer`.
|
|
- **Least privilege** — read-only Graph permission set scoped to the monitored services.
|
|
|
|
## Hardening In Progress
|
|
|
|
Implemented on a development branch and rolling into releases: identity sign-in (Entra ID / MSAL), role-based access control (Admin/Analyst/Viewer), an append-only audit trail, and certificate-based Graph auth. See `docs/PROJECT_SUMMARY.md`.
|
|
|
|
## Operator Responsibilities
|
|
|
|
- Keep the app registration's client secret/certificate in a secret store; never commit credentials; rotate anything that may have been exposed.
|
|
- Serve over HTTPS in production and restrict network exposure.
|
|
- Apply OS, .NET, SQL Server, and dependency updates.
|
|
|
|
---
|
|
|
|
## Reporting a Broken Graph API Endpoint
|
|
|
|
Microsoft occasionally changes, deprecates, or moves Graph API endpoints. If a dashboard card stops working or shows a permission error, please open an issue using this format:
|
|
|
|
**Title:** `[BROKEN API] <page name> — <endpoint>`
|
|
|
|
**Include:**
|
|
- Which page/card is affected (e.g. "Identity page — Risk Detections card")
|
|
- The error shown on screen (e.g. "403 Forbidden" or "404 Not Found")
|
|
- Your approximate date when it broke
|
|
- Link to the Microsoft changelog entry if you found one
|
|
|
|
---
|
|
|
|
## Known API Stability
|
|
|
|
| Endpoint area | Stability | Notes |
|
|
|--------------|-----------|-------|
|
|
| Risky users / sign-ins | ✅ Stable | v1.0, unchanged since 2021 |
|
|
| MFA registration details | ✅ Stable | v1.0 |
|
|
| Intune device compliance | ✅ Stable | v1.0 |
|
|
| Conditional Access policies | ✅ Stable | v1.0 |
|
|
| Defender XDR alerts (`alerts_v2`) | ✅ Stable | v1.0, replaced `alerts` in 2022 |
|
|
| Defender XDR incidents | ✅ Stable | v1.0 |
|
|
| Service health | ✅ Stable | v1.0 |
|
|
| Audit logs / sign-ins | ✅ Stable | v1.0 |
|
|
| Attack simulation | ⚠️ Watch | v1.0 but feature-flagged by license |
|
|
| Insider Risk (IRM) | ⚠️ Watch | Requires Microsoft Purview license |
|
|
| Identity health issues | ⚠️ Beta | `/beta/` endpoint — may change without notice |
|
|
| MCAS alerts | ⚠️ Watch | Merging into Defender XDR over time |
|
|
|
|
---
|
|
|
|
## Staying Ahead of Changes
|
|
|
|
Subscribe to the official Microsoft Graph changelog to get notified of breaking changes:
|
|
|
|
🔗 [https://developer.microsoft.com/en-us/graph/changelog](https://developer.microsoft.com/en-us/graph/changelog)
|
|
|
|
---
|
|
|
|
## How the App Handles Broken Endpoints
|
|
|
|
Each dashboard card fetches independently. If one Graph endpoint returns an error (403, 404, 429), that card shows an inline error message — **all other pages and cards keep working**. No single API change can break the whole dashboard.
|