Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -472,10 +472,17 @@ Deploys DCDash from an operator-selected git repository/ref into a Python
virtual environment with an application-scoped hardened systemd unit. DCDash
uses its native TLS service and public `/health` endpoint.

Source and virtualenv executables are kept under the root-owned
`hamstack_dcdash_application_dir` (default `/usr/local/lib/dcdash`). The service
account receives write access only to the database, report, backup, and
certificate paths derived from `hamstack_dcdash_install_dir` by default. The
trusted application directory must not overlap those runtime-writable paths.

```yaml
hamstack_dcdash_enabled: true
hamstack_dcdash_source_repo: "https://example.invalid/dcdash.git"
hamstack_dcdash_source_ref: main
hamstack_dcdash_application_dir: /usr/local/lib/dcdash
hamstack_dcdash_port: 8450
```

Expand Down
1 change: 1 addition & 0 deletions docs/variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -705,6 +705,7 @@ This is the exhaustive index of `hamstack_*` variables currently declared by the
| Variable | Default | Purpose |
| --- | --- | --- |
| `hamstack_dcdash_admin_username` | `admin` | Configuration value for dcdash admin username; see the services/dcdash role README for operational context. |
| `hamstack_dcdash_application_dir` | `/usr/local/lib/dcdash` | Configuration value for dcdash application dir; see the services/dcdash role README for operational context. |
| `hamstack_dcdash_autostart` | `true` | Enable/start the managed service or desktop autostart entry. |
| `hamstack_dcdash_backup_dir` | `{{ hamstack_dcdash_install_dir }}/backups` | Configuration value for dcdash backup dir; see the services/dcdash role README for operational context. |
| `hamstack_dcdash_bind_address` | `0.0.0.0` | Address on which the managed service binds. |
Expand Down
8 changes: 8 additions & 0 deletions roles/services/dcdash/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,4 +16,12 @@ The application source remains separate from HamStack. Point
`hamstack_dcdash_source_repo` at the desired DCDash git repository/ref and put
`vault_hamstack_dcdash_admin_password` in the local Vault.

HamStack keeps the executable source and Python virtual environment beneath the
root-owned `hamstack_dcdash_application_dir`. The `dcdash` service account can
read that tree but cannot modify it. `hamstack_dcdash_install_dir` remains the
default persistent runtime-data root for the database, reports, backups, and
certificates, and the systemd unit grants write access only to those configured
runtime paths. The role rejects configurations where the trusted application
directory overlaps a runtime-writable path.

The role verifies the application's public `/health` endpoint after startup.
1 change: 1 addition & 0 deletions roles/services/dcdash/defaults/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ hamstack_dcdash_source_mode: git
hamstack_dcdash_source_repo: ''
hamstack_dcdash_source_ref: main
hamstack_dcdash_install_dir: /opt/dcdash
hamstack_dcdash_application_dir: /usr/local/lib/dcdash
hamstack_dcdash_user: dcdash
hamstack_dcdash_group: dcdash
hamstack_dcdash_bind_address: 0.0.0.0
Expand Down
96 changes: 87 additions & 9 deletions roles/services/dcdash/tasks/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,13 @@
that:
- hamstack_dcdash_source_mode == 'git'
- hamstack_dcdash_source_repo | length > 0
- hamstack_dcdash_application_dir.startswith('/')
- hamstack_dcdash_application_dir | regex_replace('/+$', '') | length > 1
- vault_hamstack_dcdash_admin_password | default('') | length >= 12
fail_msg: >-
DCDash currently expects a git source repository and a Vault-backed
admin password of at least 12 characters.
admin password of at least 12 characters. Its trusted application
directory must be an absolute path other than the filesystem root.

- name: Install DCDash build/runtime prerequisites
ansible.builtin.apt:
Expand Down Expand Up @@ -44,6 +47,42 @@
DCDash 2.9 requires Python 3.11 or 3.12; this host reports
{{ _hamstack_dcdash_python_version.stdout }}.

- name: Resolve DCDash trusted and runtime paths
ansible.builtin.command:
argv:
- python3
- -c
- >-
import json, os, sys;
print(json.dumps([os.path.realpath(path) for path in sys.argv[1:]]))
- "{{ hamstack_dcdash_application_dir }}"
- "{{ hamstack_dcdash_install_dir }}"
- "{{ hamstack_dcdash_db_path | dirname }}"
- "{{ hamstack_dcdash_reports_dir }}"
- "{{ hamstack_dcdash_backup_dir }}"
- "{{ hamstack_dcdash_cert_file | dirname }}"
- "{{ hamstack_dcdash_key_file | dirname }}"
register: _hamstack_dcdash_resolved_paths
changed_when: false

- name: Validate DCDash trusted application boundary
ansible.builtin.assert:
that:
- _hamstack_dcdash_application_path != '/'
- item != '/'
- _hamstack_dcdash_application_path != item
- not _hamstack_dcdash_application_path.startswith(item + '/')
- not item.startswith(_hamstack_dcdash_application_path + '/')
fail_msg: >-
hamstack_dcdash_application_dir must not overlap any DCDash
runtime-writable path after resolving aliases and symbolic links.
loop: "{{ (_hamstack_dcdash_resolved_paths.stdout | from_json)[1:] }}"
loop_control:
label: "{{ item }}"
vars:
_hamstack_dcdash_application_path: >-
{{ (_hamstack_dcdash_resolved_paths.stdout | from_json)[0] }}

- name: Create DCDash service group
ansible.builtin.group:
name: "{{ hamstack_dcdash_group }}"
Expand All @@ -58,7 +97,45 @@
home: "{{ hamstack_dcdash_install_dir }}"
create_home: false

- name: Create DCDash install directory
- name: Inspect existing DCDash trusted application paths
ansible.builtin.stat:
path: "{{ item }}"
follow: false
get_attributes: false
get_checksum: false
get_mime: false
loop:
- "{{ hamstack_dcdash_application_dir }}"
- "{{ hamstack_dcdash_application_dir }}/source"
- "{{ hamstack_dcdash_application_dir }}/venv"
register: _hamstack_dcdash_trusted_paths

- name: Refuse unsafe DCDash trusted application paths
ansible.builtin.assert:
that:
- not item.stat.exists or item.stat.isdir
- not item.stat.exists or item.stat.uid == 0
- not item.stat.exists or item.stat.mode[-2] not in ['2', '3', '6', '7']
- not item.stat.exists or item.stat.mode[-1] not in ['2', '3', '6', '7']
fail_msg: >-
Refusing to process {{ item.item }} with privileged Git or pip because
it is not a root-owned directory protected from non-root writes.
loop: "{{ _hamstack_dcdash_trusted_paths.results }}"
loop_control:
label: "{{ item.item }}"

- name: Create DCDash trusted application directories
ansible.builtin.file:
path: "{{ item }}"
state: directory
owner: root
group: root
mode: "0755"
loop:
- "{{ hamstack_dcdash_application_dir }}"
- "{{ hamstack_dcdash_application_dir }}/source"

- name: Create DCDash runtime root
ansible.builtin.file:
path: "{{ hamstack_dcdash_install_dir }}"
state: directory
Expand All @@ -69,7 +146,7 @@
- name: Check out DCDash source
ansible.builtin.git:
repo: "{{ hamstack_dcdash_source_repo }}"
dest: "{{ hamstack_dcdash_install_dir }}"
dest: "{{ hamstack_dcdash_application_dir }}/source"
version: "{{ hamstack_dcdash_source_ref }}"
update: true
force: false
Expand All @@ -91,17 +168,18 @@

- name: Install DCDash Python environment
ansible.builtin.pip:
name: "{{ hamstack_dcdash_install_dir }}"
virtualenv: "{{ hamstack_dcdash_install_dir }}/.venv"
name: "{{ hamstack_dcdash_application_dir }}/source"
virtualenv: "{{ hamstack_dcdash_application_dir }}/venv"
virtualenv_command: "python3 -m venv"
state: present
register: _hamstack_dcdash_python

- name: Correct DCDash source ownership
- name: Keep DCDash application tree root-owned
ansible.builtin.file:
path: "{{ hamstack_dcdash_install_dir }}"
owner: "{{ hamstack_dcdash_user }}"
group: "{{ hamstack_dcdash_group }}"
path: "{{ hamstack_dcdash_application_dir }}"
owner: root
group: root
mode: "u=rwX,g=rX,o=rX"
recurse: true

- name: Render DCDash environment file
Expand Down
8 changes: 4 additions & 4 deletions roles/services/dcdash/templates/dcdash.service.j2
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,15 @@ Type=simple
User={{ hamstack_dcdash_user }}
Group={{ hamstack_dcdash_group }}
UMask=0077
WorkingDirectory={{ hamstack_dcdash_install_dir }}
WorkingDirectory={{ hamstack_dcdash_application_dir }}/source
EnvironmentFile=/etc/default/dcdash
ExecStartPre={{ hamstack_dcdash_install_dir }}/.venv/bin/python -c "from dcdash.security.cert_gen import generate_self_signed_cert; generate_self_signed_cert('{{ hamstack_dcdash_cert_file }}', '{{ hamstack_dcdash_key_file }}')"
ExecStart={{ hamstack_dcdash_install_dir }}/.venv/bin/gunicorn -c {{ hamstack_dcdash_install_dir }}/gunicorn.conf.py --bind {{ hamstack_dcdash_bind_address }}:{{ hamstack_dcdash_port }} --certfile {{ hamstack_dcdash_cert_file }} --keyfile {{ hamstack_dcdash_key_file }} --workers 1 --threads 4 --timeout 30 --access-logfile - --error-logfile - "dcdash.app:create_app()"
ExecStartPre={{ hamstack_dcdash_application_dir }}/venv/bin/python -c "from dcdash.security.cert_gen import generate_self_signed_cert; generate_self_signed_cert('{{ hamstack_dcdash_cert_file }}', '{{ hamstack_dcdash_key_file }}')"
ExecStart={{ hamstack_dcdash_application_dir }}/venv/bin/gunicorn -c {{ hamstack_dcdash_application_dir }}/source/gunicorn.conf.py --bind {{ hamstack_dcdash_bind_address }}:{{ hamstack_dcdash_port }} --certfile {{ hamstack_dcdash_cert_file }} --keyfile {{ hamstack_dcdash_key_file }} --workers 1 --threads 4 --timeout 30 --access-logfile - --error-logfile - "dcdash.app:create_app()"
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths={{ hamstack_dcdash_install_dir }} {{ hamstack_dcdash_db_path | dirname }} {{ hamstack_dcdash_reports_dir }} {{ hamstack_dcdash_backup_dir }} {{ hamstack_dcdash_cert_file | dirname }} {{ hamstack_dcdash_key_file | dirname }}
ReadWritePaths={{ hamstack_dcdash_db_path | dirname }} {{ hamstack_dcdash_reports_dir }} {{ hamstack_dcdash_backup_dir }} {{ hamstack_dcdash_cert_file | dirname }} {{ hamstack_dcdash_key_file | dirname }}
ProtectKernelModules=yes
ProtectKernelTunables=yes
ProtectControlGroups=yes
Expand Down
Loading