mirror of
https://github.com/sameerk27/vigil365.git
synced 2026-07-02 10:39:35 +02:00
81 lines
4.4 KiB
Markdown
81 lines
4.4 KiB
Markdown
|
# Vigil365 — Project Summary
|
||
|
|
|
||
|
|
A self-hosted, open-source Microsoft 365 security dashboard. It aggregates
|
||
|
|
security posture and alerts from across the Microsoft 365 stack — Defender XDR,
|
||
|
|
Entra ID, Intune, Exchange Online, and Purview — into a single pane of glass.
|
||
|
|
All data stays in the customer's own tenant/infrastructure; there is no
|
||
|
|
third-party SaaS in the data path.
|
||
|
|
|
||
|
|
> **Status note:** the public `master` branch reflects the released app. A large
|
||
|
|
> authentication / multi-user / setup update (sections marked 🆕 below) is on the
|
||
|
|
> `feature/microsoft-login` branch, validated locally, not yet merged/published.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## What it does
|
||
|
|
|
||
|
|
| Area | Coverage |
|
||
|
|
|------|----------|
|
||
|
|
| Identity | Risky users, risky sign-ins, risk detections, MFA coverage, PIM, foreign sign-ins |
|
||
|
|
| Devices | Intune compliance, non-compliant + stale devices, Defender endpoint alerts |
|
||
|
|
| Email | Defender for Office 365 alerts (malware/phish/spam) |
|
||
|
|
| Incidents | Unified Defender XDR incidents + alerts |
|
||
|
|
| Compliance | DLP, MCAS, insider-risk, attack simulations |
|
||
|
|
| Service Health | M365 service advisories |
|
||
|
|
| Conditional Access | Policy inventory + state |
|
||
|
|
| Audit / Sign-ins | Unified audit log, geographic sign-in view |
|
||
|
|
| Alert Center | Custom alert policies, server-side evaluation, notifications (Teams/Email/webhook), per-alert snooze, silent auto-resolve |
|
||
|
|
|
||
|
|
## Architecture & stack
|
||
|
|
|
||
|
|
| Layer | Technology |
|
||
|
|
|-------|-----------|
|
||
|
|
| Backend | ASP.NET Core 8 Minimal API |
|
||
|
|
| Frontend | React 18 + TypeScript + Vite (SPA) |
|
||
|
|
| Data source | Microsoft Graph API — app-only (client credentials), **read-only** |
|
||
|
|
| Scheduler | .NET BackgroundService, 15-minute collection cycle |
|
||
|
|
| Storage | SQL Server Express by default; scales to SQL Server / Azure SQL (connection-string swap, no code change) |
|
||
|
|
|
||
|
|
## Security posture
|
||
|
|
|
||
|
|
- **Authentication** 🆕 — Microsoft/Entra ID login (MSAL); backend validates Bearer tokens (audience-scoped).
|
||
|
|
- **Authorization** 🆕 — role-based access (Admin / Analyst / Viewer). Roles are app-managed (stored in-app), not Entra App Roles; enforced server-side via authorization policies and a claims transformation.
|
||
|
|
- **User management** 🆕 — in-app admin UI to add/pre-provision, change roles, remove users, and send/resend access-notification emails. Last-admin lockout guards.
|
||
|
|
- **Audit trail** 🆕 — append-only log of security-relevant actions (user add/role-change/remove/invite, settings, setup), with actor identity from the validated token.
|
||
|
|
- **Encryption at rest** — secrets (SMTP password, webhook URLs, Graph client secret) DPAPI-encrypted; SQL connection uses `Encrypt=True`.
|
||
|
|
- **Encryption in transit** 🆕 — HSTS + HTTPS redirection enforced outside Development; TLS via reverse proxy or Kestrel certificate (documented).
|
||
|
|
- **Least privilege** — Graph permissions are all `*.Read.All`; the app never writes to the tenant.
|
||
|
|
- **Network model** — designed as an internal/self-hosted tool; not a public multi-tenant SaaS.
|
||
|
|
|
||
|
|
## Install model 🆕
|
||
|
|
|
||
|
|
Reduced to ~3 steps:
|
||
|
|
1. `install.ps1` — checks prerequisites, builds the frontend, publishes the API, optional Windows-service install.
|
||
|
|
2. One-time Entra app registration (app-only Graph permissions + SPA redirect URI + `access_as_user` scope).
|
||
|
|
3. Sign in (first user becomes Admin) → **in-app first-run setup wizard** to enter Graph credentials (stored encrypted; no JSON editing).
|
||
|
|
|
||
|
|
## Roadmap
|
||
|
|
|
||
|
|
**Recently landed (local branch):** Microsoft login, RBAC, in-app user management + invites, audit trail, production HTTPS enforcement, one-shot installer + first-run setup wizard.
|
||
|
|
|
||
|
|
**In progress / planned:**
|
||
|
|
- Trends & history page — metric snapshots over time (risky users, compliance, secure score) with exec-friendly up/down/flat readouts.
|
||
|
|
- Certificate-based Graph auth (replacing client secret) + secret-vault integration.
|
||
|
|
- Data retention / pruning policies.
|
||
|
|
- `register-app.ps1` to script the Entra app registration.
|
||
|
|
- Optional SQLite backend to drop the SQL Server dependency.
|
||
|
|
- Docker / docker-compose deployment.
|
||
|
|
- CI with automated tests; dependency scanning.
|
||
|
|
|
||
|
|
## Scope & honest limitations
|
||
|
|
|
||
|
|
- Not a SIEM — no raw-log ingestion, KQL hunting, or SOAR. It complements tools like Microsoft Sentinel rather than replacing them.
|
||
|
|
- Visibility is bounded by what Microsoft Graph exposes.
|
||
|
|
- Single-tenant, self-hosted by design.
|
||
|
|
- Historical trends accrue from when snapshotting begins (no retroactive history).
|
||
|
|
|
||
|
|
## Links
|
||
|
|
|
||
|
|
- Repository: https://github.com/sameerk27/vigil365
|
||
|
|
- License: MIT
|