AuditGuard

An audit and compliance monitoring platform, plus a simulated enterprise portal that acts as the monitored target system. Built for the 7003SCN Advanced Software Development group assignment.

The two applications are completely decoupled. They communicate only through an authenticated HTTP API. The portal can write to the audit trail and has no route, credential or database mapping that would let it read, change or delete anything held there.

Components

Component	Stack	Port
Audit platform API	Python 3.13, FastAPI, SQLAlchemy, Alembic, psycopg2	8000
Audit platform interface	React 18, Vite	5173
Simulation portal API	Python 3.13, FastAPI, SQLAlchemy, Alembic, psycopg2	8100
Simulation portal interface	React 18, Vite	5174
Database	PostgreSQL 18, two separate schemas	managed

Both applications use one PostgreSQL instance but live in separate schemas, audit_platform and portal. Neither application's SQLAlchemy metadata or Alembic history can reach the other's tables.

Layout

project/
  .env                        gitignored, never committed
  .env.example                template
  requirements.txt            shared Python dependencies
  pytest.ini
  audit-platform/
    backend/
      alembic/                migrations for the audit_platform schema
      app/
        config.py             settings read from .env
        db.py                 engine, session and declarative base
        models.py             audit data model
        schemas.py            Pydantic schemas, where normalisation begins
        security.py           password hashing, API keys and tokens
        deps.py               authentication and the capability matrix
        policy_engine.py      the configurable rules
        seed.py               reference data and a fortnight of history
        reevaluate.py         re-run the engine over stored events
        main.py               FastAPI application
        routers/              auth, ingest, events, stats, violations, policies,
                              sources, users
    frontend/                 React interface
  simulation-portal/
    backend/
      alembic/                migrations for the portal schema
      app/
        audit_client.py       the logging middleware transport and outbox
        main.py               login, directory, record operations, activity log
        models.py, security.py, seed.py, config.py, db.py
    frontend/                 React interface
  tests/                      pytest suite

Getting started

1. Configuration

cp .env.example .env

Fill in DATABASE_URL, JWT_SECRET and PORTAL_SECRET. .env is gitignored and must never be committed. PORTAL_API_KEY is written for you by the audit platform seed script.

2. Python environment

py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

3. Migrations and seed data

cd audit-platform\backend
..\..\.venv\Scripts\python.exe -m alembic upgrade head
..\..\.venv\Scripts\python.exe -m app.seed

cd ..\..\simulation-portal\backend
..\..\.venv\Scripts\python.exe -m alembic upgrade head
..\..\.venv\Scripts\python.exe -m app.seed

The audit platform seed registers the simulation-portal source, issues its API key and writes that key back into .env, so run the audit platform seed first.

4. Run everything

# terminal 1, audit platform API
cd audit-platform\backend
..\..\.venv\Scripts\python.exe -m uvicorn app.main:app --port 8000

# terminal 2, simulation portal API
cd simulation-portal\backend
..\..\.venv\Scripts\python.exe -m uvicorn app.main:app --port 8100

# terminal 3, audit platform interface
cd audit-platform\frontend && npm install && npm run dev

# terminal 4, simulation portal interface
cd simulation-portal\frontend && npm install && npm run dev

Then open the audit platform at http://localhost:5173 and the portal at http://localhost:5174.

Seeded accounts

Audit platform, at http://localhost:5173:

Email	Password	Role
admin@auditguard.example	AdminPass123!	ADMINISTRATOR
auditor@auditguard.example	AuditorPass123!	AUDITOR
officer@auditguard.example	OfficerPass123!	COMPLIANCE_OFFICER

Simulation portal, at http://localhost:5174: j.okafor, m.henderson or s.patel, all with the password Portal123!.

These are demonstration credentials for a local instance only.

The common event schema

Every monitored system posts events in one shape. Adopting this shape is the only integration work a new source has to do, which is what makes the platform source agnostic.

{
  "events": [
    {
      "actor": "j.okafor",
      "action": "RECORD_DELETE_ATTEMPT",
      "resource": "payroll/7",
      "outcome": "DENIED",
      "occurred_at": "2026-08-14T11:05:00Z",
      "ip_address": "10.20.4.31",
      "metadata": { "reason": "table_protected" }
    }
  ]
}

Posted to POST /api/v1/ingest with the headers X-Source-Id and X-API-Key.

Rules applied on the way in:

the action must be one of the known actions, and it is upper cased
the outcome must be SUCCESS, FAILURE or DENIED
occurred_at is converted to UTC, and a naive value is treated as UTC
the stored source_id is taken from the authenticated key, never from the body, so one source cannot impersonate another
a batch that contains one bad event is rejected in full, with no partial write

The policy engine

A policy is data, not code: a name, a rule type, a severity, a JSON parameter block and an enabled flag. Adding a rule type means adding one function and one entry in RULES.

Rule type	Parameters	Default severity
`FAILED_LOGIN_THRESHOLD`	`threshold`, `window_minutes`	HIGH
`OUTSIDE_WORKING_HOURS`	`start`, `end`, `days`, `timezone`	MEDIUM
`UNAUTHORISED_DELETE`	`protected_resources`, `include_successful`	CRITICAL

Every stored event is evaluated against every enabled policy at ingestion time. A candidate violation carries a dedupe key, so one burst of failed logins produces one violation rather than one per attempt, and a re-evaluation never duplicates a finding. app.reevaluate re-runs the engine over the whole event history, which is what you want after retuning a policy.

Each violation records both occurred_at, the time of the breach itself, and detected_at, the time the engine recorded it. The trend charts are drawn on occurred_at.

Roles

Capability	Auditor	Administrator	Compliance officer
View dashboards, logs and violations	yes	yes	yes
Change case state, assign and annotate	no	yes	yes
Manage policies	no	yes	no
Manage sources and API keys	no	yes	no
Manage users	no	yes	no

The matrix lives in one place, app/deps.py, and every route declares the capability it requires. The interface reads the same matrix from GET /api/v1/auth/capabilities to decide what to render, but the server checks every request independently, so hiding a control is never the security boundary.

Write only isolation

The integrity of the audit trail rests on the monitored system being unable to read or alter it. This is enforced, not assumed.

A source API key satisfies exactly one dependency, authenticate_source, which is attached to exactly one route, POST /api/v1/ingest.
Every other route depends on get_current_user, which requires a user bearer token and rejects anything else with 401.
The platform exposes no delete route for events or violations at all.
The portal's SQLAlchemy metadata is bound to the portal schema and never imports an audit platform model, so there is no mapped path to an audit table.
tests/test_rbac.py::TestMonitoredSourceIsolation asserts all of this route by route.

Tests

# backend, 131 tests
.\.venv\Scripts\python.exe -m pytest

# audit platform interface, 15 tests
cd audit-platform\frontend && npx vitest run

# simulation portal interface, 9 tests
cd simulation-portal\frontend && npx vitest run

The pytest suite runs against an in memory SQLite database so it is fast and cannot touch the real audit trail. It covers policy rule boundaries, ingestion authentication, normalisation, the capability matrix endpoint by endpoint, monitored source isolation, the case state machine and log explorer filtering.

Demonstrating a breach

Sign in to the portal at http://localhost:5174 and fail the password five times. The repeated failed login policy raises a HIGH violation.
Sign in properly, open a payroll record and delete it. The portal refuses, and the refused attempt raises a CRITICAL violation.
Any activity before 09:00 or after 18:00 local time, or at a weekend, raises a MEDIUM violation.

Each of these appears on the audit platform dashboard, in the log explorer and on the case board within a second or two.

Varrad/7003SCN_AuditGaurd_CodeBase

About

Resources

Stars

Watchers

Forks

Releases

Languages