# Web service

## Modules and blueprints

User accounts are enabled by default (`user_accounts` is `true` in `config/generic.json`).
They activate the blueprints for authentication, sessions, comments, bundles, etc.
Set it to `false` for a read-only instance.

Initialization of the database:

```bash
$ poetry run flask --app website.app db_init
```

As explained in a previous section.

The views of the application are structured in Blueprints.

## Security considerations

Vulnerabilities are imported through various feeders that are not connected to the web service.

Two-factor authentication can be enforced for users of the platform.
Additionally, each user can generate an API key to use the API programmatically.

### Network exposure and transport

The bundled launcher and Docker image are tuned for a quick single-host or local
setup. Their default network bindings are a deployment convenience, **not** a
production security posture: the platform expects the operator to place the
right network boundaries and transport protection around it.

**Front the web listener with a TLS-terminating reverse proxy.**
The website is served by Gunicorn over plain HTTP on `0.0.0.0:10001` (see
`bin/start_website.py` and `.docker/website/Dockerfile`). Do not expose that
port directly to clients. Put a reverse proxy (nginx, Apache, Caddy, …) in
front of it to terminate TLS, redirect HTTP to HTTPS, and emit HSTS. When the
application is served over HTTPS, harden the session cookies in
`config/website.py`:

```python
SESSION_COOKIE_SECURE = True
SESSION_COOKIE_HTTPONLY = True
PREFERRED_URL_SCHEME = "https"
```

The launcher already wires `ProxyFix` and `--forwarded-allow-ips`, so the
application trusts the `X-Forwarded-*` headers set by the fronting proxy.

**Keep the Kvrocks backend off untrusted networks.**
Kvrocks stores the vulnerability corpus and speaks the Redis protocol on TCP
`10002`. The shipped Compose configurations publish `10002:10002`, the fallback
Docker launcher publishes the same port, and `storage/kvrocks.conf` binds
`0.0.0.0`. Authentication and TLS are disabled by default. Anything that can
reach that port can access the datastore directly, bypassing the web
application's authentication and authorization.

Choose network restrictions that match the deployment:

- In `docker-compose.yml` and `docker-compose_sep.yml`, remove the `ports`
  entry from `kvrocks_master`. Application containers use the Compose service
  name and do not need the datastore published on the host. If host access is
  needed, bind the published port to loopback instead:

  ```yaml
  ports:
    - "127.0.0.1:10002:10002"
  ```

- For the fallback command in `storage/run_kvrocks.sh`, replace
  `-p10002:10002` with `-p127.0.0.1:10002:10002`.
- For a bare-metal deployment, change the `bind` directive in
  `storage/kvrocks.local.conf` (see [Performance tuning](performance-tuning.md#kvrocks-primary-storage)) to `bind 127.0.0.1 ::1`, or bind it to a dedicated
  private interface protected by network access controls.
- If remote access to Kvrocks is genuinely required, also configure TLS.
  Kvrocks supports `requirepass`, but the application does not currently
  configure a storage password; enabling it without updating all storage
  clients will prevent the application from connecting.

The Valkey/Redis cache is bound to a Unix socket (`cache/cache.sock`) by
default and is not exposed over the network.

## Permissions

Permissions are managed with roles. See [Role-based access control](rbac.md).

## Authentication workflows

### Sign-up

| Step | Endpoint | Methods | Rule | Comment |
|------|----------|---------|------|---------|
| 1 | user_bp.signup | GET, POST | /user/signup | Sign-up with login and email. A confirmation email is sent to the user with a token in a URL. |
| 2 | user_bp.confirm_account | GET, POST | /user/confirm_account/\<string:token\> | token: from the received email. The user can now choose a password. |
| 3 | user_bp.login | GET, POST | /user/login | Authentication with login and password |
| 4 | user_bp.setup_two_factor_auth | GET | /user/setup-2fa | Set-up TFA with QRCode (or token) provided by the server |
| 5 | user_bp.verify_two_factor_auth | GET, POST | /user/verify-2fa | Verify TFA with token provided by the client app |

### Login

| Endpoint | Methods | Rule |
|----------|---------|------|
| user_bp.login | GET, POST | /user/login |
| user_bp.verify_two_factor_auth | GET, POST | /user/verify-2fa |
| user_bp.verify_two_factor_recovery | GET, POST | /user/verify-2fa-recovery |

Single sign-on uses `/user/login/sso`; see [SSO](sso.md).
