From 494f30d6c3da8c628e22276593c57b563508ab1a Mon Sep 17 00:00:00 2001 From: janis steiner Date: Sun, 10 May 2026 10:46:54 +0200 Subject: [PATCH] adding docs --- README.md | 139 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..e481d7d --- /dev/null +++ b/README.md @@ -0,0 +1,139 @@ +# Neptune - Cybersecurity Incident Journal + +A self-hosted web application for cybersecurity teams to track, document, and visualize security incidents. + +## Features + +- **Incident Timeline** — chronological log of security events with severity levels, team assignments, and comments +- **Network Map** — interactive canvas-based network topology diagram (drag/drop nodes, draw connections, add zone shapes) +- **Document Templates** — structured forms for standardized documentation: Deployments, Attacks, Incident Reports, Remediations, and Exercises +- **Team-based Organization** — built-in teams: Blue Team, Red Team, SOC, Threat Intel +- **External Authentication** — login via [Jakach Auth](https://auth.jakach.ch) + +## Prerequisites + +- [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/) +- A Jakach Auth account for authentication +- Port **8081** available on the host (configurable) + +## Quick Start + +```bash +git clone https://git.jakach.ch/jakach/armeech-neptune.git +cd armech-neptune +docker compose up -d +``` + +Open [http://localhost:8081](http://localhost:8081) in your browser. + +The first user to log in becomes an **admin**. Subsequent users are assigned the **user** role by default. + +## Configuration + +### Environment Variables (backend) + +Set these on the `php` service in `docker-compose.yml`: + +| Variable | Default | Description | +|---|---|---| +| `DB_HOST` | `mysql` | MySQL hostname | +| `DB_NAME` | `neptune` | Database name | +| `DB_USER` | `neptune` | Database user | +| `DB_PASS` | `neptune_pass` | Database password | + +### MySQL Root Password + +The MySQL root password defaults to `neptune_root_pass`. Change it in the `mysql` and `php` environment sections of `docker-compose.yml`. + +### Port + +The web interface binds to `8081:80` by default. Change the left side of the port mapping in `docker-compose.yml` to use a different port. + +## Project Structure + +``` +├── backend/ +│ ├── api/index.php # Single-file REST API (all endpoints) +│ └── config/database.php # Database connection & auto-migration +├── docker/ +│ ├── Dockerfile.php # PHP 8.2-FPM image build +│ ├── nginx.conf # Nginx reverse proxy config +│ ├── php.ini # PHP session configuration +│ └── init.sql # Database schema and seed data +├── frontend/ +│ ├── index.html # Single-page application (SPA) +│ ├── assets/js/app.js # Frontend logic (Vanilla JS) +│ └── assets/css/style.css # Custom dark theme styles +├── docker-compose.yml # Container orchestration +└── .gitea/workflows/ # CI/CD pipeline (Gitea Actions) +``` + +## API Endpoints + +All API routes are under `/api/`. Authentication is via PHP session (set on login). + +| Method | Path | Auth | Description | +|---|---|---|---| +| GET | `/api/session` | No | Check login session status | +| POST | `/api/login` | No | Authenticate via Jakach Auth token | +| POST | `/api/logout` | No | Destroy session | +| GET | `/api/registration` | No | Check if new user registration is enabled | +| POST | `/api/registration` | Admin | Enable/disable new user registration | +| GET | `/api/settings` | Admin | List all registered users | +| POST | `/api/settings` | Admin | Add user by Jakach Auth token | +| DELETE | `/api/settings` | Admin | Remove a user | +| GET/POST | `/api/teams[/{id}]` | Yes | List / create teams | +| GET/POST/PUT/DELETE | `/api/events[/{id}]` | Yes | CRUD timeline events | +| GET/POST | `/api/comments` | Yes | List / create comments on events | +| GET/POST/PUT/DELETE | `/api/nodes[/{id}]` | Yes | CRUD network map nodes | +| GET/POST/DELETE | `/api/links[/{id}]` | Yes | CRUD network connections | +| GET/POST/PUT/DELETE | `/api/shapes[/{id}]` | Yes | CRUD network zone shapes | +| GET/POST/PUT/DELETE | `/api/documents[/{id}]` | Yes | CRUD structured documents | + +## User Roles + +- **admin** — Access to Settings modal (add/remove users, toggle registration), full CRUD on all resources +- **user** — Full CRUD on events, documents, network map. Cannot access Settings. + +Registration can be disabled by an admin via **Settings → New User Registration** toggle. When disabled, only existing users can log in; new users see a "Registration is disabled" error. + +## Deployment + +### Production (Docker Compose) + +```bash +docker compose up -d --build +``` + +### CI/CD (Gitea Actions) + +The project includes a `.gitea/workflows/deploy.yml` that auto-deploys on push to `main`. Configure these [secrets/variables](https://docs.gitea.com/usage/actions): + +| Secret/Variable | Description | +|---|---| +| `SSH_KEY` | Private SSH key for deployment server | +| `SSH_USER` (var) | SSH username | +| `SSH_IP` (var) | Deployment server IP | +| `GIT_USER` (var) | Gitea username for repo access | +| `GIT_TOKEN` (secret) | Gitea personal access token | + +## Updating + +```bash +git pull origin main +docker compose down +docker compose up -d --build +``` + +Database schema migrations run automatically on container startup via `backend/config/database.php`. + +## Tech Stack + +| Layer | Technology | +|---|---| +| Frontend | Vanilla JavaScript, Bootstrap 5.3, Font Awesome 6, HTML5 Canvas | +| Backend | PHP 8.2 (no framework) | +| Database | MySQL 8.0 | +| Web Server | Nginx (reverse proxy to PHP-FPM) | +| Auth | External — Jakach Auth (OAuth-like token exchange) | +| Containerization | Docker Compose (nginx, php, mysql) | \ No newline at end of file