# 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) |