dev

.claude/skills/gh-workflow-monitor/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: gh-workflow-monitor
+description: Monitor GitHub workflows, propose fixes for failures, and report status
+disable-model-invocation: true
+---
+
+# GitHub Workflow Monitor
+
+Use the `gh` for GitHub operations.
+
+## Step 1: Check current branch.
+
+## Step 2: If the branch is not green, find the GitHub Actions workflow run associated with the current branch. Use the gh cli.
+
+## Step 3: Monitor the workflow run for failures.
+
+## Step 4: If the workflow run fails, propose a fix.
+
+## Step 5: If the workflow run succeeds, exit plan mode and report the status.

.claude/skills/implement/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: implement
+description: Assess and implement a Ground Control requirement, ensuring GitHub issue and traceability links exist
+argument-hint: <requirement-uid>
+disable-model-invocation: true
+---
+
+# Implement Requirement: $ARGUMENTS
+
+## Step 1: Fetch Requirement and Ensure GitHub Issue Exists
+
+1. Enter plan mode.
+
+2. Use the `gc_get_requirement` MCP tool with uid `GC-$ARGUMENTS` to fetch the requirement details. Note the requirement's UUID, title, statement, status, and wave.
+
+3. Use the `gc_get_traceability` MCP tool with the requirement's UUID to check for existing traceability links. Look for a link with artifact_type `GITHUB_ISSUE`.
+
+4. If NO GitHub issue link exists:
+   - Use the `gc_create_github_issue` MCP tool with uid `$ARGUMENTS` to create a GitHub issue and auto-link it.
+
+5. If a GitHub issue link DOES exist, note the issue number from the artifact_identifier.
+
+6. Run `gh issue develop <issue-number> --checkout --base dev` to switch to the issue branch.
+
+## Step 2: Read the GitHub Issue
+
+Run `gh issue view <issue-number>` to read the full issue details including description, labels, and comments.
+
+## Step 3: Assess Codebase Coverage
+
+Explore the codebase to determine whether the requirement described in the issue is already satisfied by existing code:
+- Search for relevant classes, methods, tests, and configurations
+- Check if the described behavior already exists
+- Review any existing traceability links (IMPLEMENTS, TESTS) from Step 1
+
+## Step 4: Plan or Report
+
+- **If the requirement is NOT yet met**: Plan the implementation. Identify which files need to be created or modified, what tests to write, and what approach to take. Enter plan mode.
+- Your plans must respect the coding standards and classification levels in ADR-012.
+- Plans must include updating the changelog, readme, and docs as appropriate.
+- **If the requirement IS already met**: Report that the requirement is satisfied and identify which code satisfies it.
+
+## Step 5: Ensure Traceability Links
+
+After implementation is complete (or if already implemented):
+- use the `gc_create_traceability_link` MCP tool to create any missing links:
+  - `IMPLEMENTS` links from the requirement to the code files that implement it
+  - `TESTS` links from the requirement to the test files that verify it
+  - Only create links that don't already exist (check the traceability data from Step 1).
+- use the `gc_transition_status` MCP tool to transition the requirement to `ACTIVE` if it was `DRAFT`.
+
+Do not update the Changelog if all you did was operate Ground Control tools.

.dockerignore

@@ -0,0 +1,20 @@
+.git
+.github
+.venv
+.pytest_cache
+.mypy_cache
+__pycache__
+*.pyc
+node_modules
+containers/
+docs/
+notes/
+coverage.xml
+.coverage
+*.egg-info
+dist/
+build/
+.svelte-kit
+web/node_modules
+web/.svelte-kit
+web/tests

.env.example

@@ -26,3 +26,7 @@ MISP_ADMIN_PASSWORD=MispAdmin2024!
 THEHIVE_SECRET=aptl-thehive-lab-secret-key-2024-purple
 SHUFFLE_ADMIN_PASSWORD=ShuffleAdmin2024!
 SHUFFLE_API_KEY=31a211c4-ea5c-4a49-b022-5e2434e758a7
+
+# Grafana (OTel observability stack)
+GRAFANA_ADMIN_USER=admin
+GRAFANA_ADMIN_PASSWORD=CHANGE_ME_grafana_password

.github/workflows/deploy.yml

@@ -0,0 +1,139 @@
+name: Deploy Lab
+
+on:
+  push:
+    branches: [dev]
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: 'Target environment'
+        type: environment
+        required: true
+
+jobs:
+  deploy:
+    # On push to dev: use DEFAULT_DEPLOY_ENVIRONMENT repo variable.
+    # On manual dispatch: use the selected environment.
+    # If neither exists, the job is skipped entirely — users who
+    # only run locally are unaffected.
+    environment: ${{ inputs.environment || vars.DEFAULT_DEPLOY_ENVIRONMENT }}
+    if: ${{ inputs.environment || vars.DEFAULT_DEPLOY_ENVIRONMENT != '' }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Connect to Tailscale
+        if: vars.DEPLOY_VIA_TAILSCALE == 'true'
+        uses: tailscale/github-action@v4
+        with:
+          oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
+          oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
+          tags: tag:ci
+
+      - name: Set up SSH
+        env:
+          SSH_PRIVATE_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
+        run: |
+          mkdir -p ~/.ssh
+          echo "$SSH_PRIVATE_KEY" > ~/.ssh/deploy_key
+          chmod 600 ~/.ssh/deploy_key
+
+      - name: Deploy
+        env:
+          DEPLOY_HOST: ${{ vars.DEPLOY_HOST }}
+          DEPLOY_USER: ${{ vars.DEPLOY_USER }}
+          DEPLOY_DIR: ${{ vars.DEPLOY_DIR || '/opt/aptl' }}
+          DEPLOY_SSH_PORT: ${{ vars.DEPLOY_SSH_PORT || '22' }}
+        run: |
+          SSH="ssh -i ~/.ssh/deploy_key -p ${DEPLOY_SSH_PORT} -o StrictHostKeyChecking=accept-new ${DEPLOY_USER}@${DEPLOY_HOST}"
+
+          # Stop any running lab before syncing code
+          $SSH "cd ${DEPLOY_DIR} && docker stop \$(docker ps -q) 2>/dev/null; docker rm \$(docker ps -aq) 2>/dev/null; docker network prune -f 2>/dev/null; true"
+
+          # Sync repo from runner to remote (runner has repo access, remote doesn't)
+          $SSH "mkdir -p ${DEPLOY_DIR}"
+          rsync -az --delete \
+            -e "ssh -i ~/.ssh/deploy_key -p ${DEPLOY_SSH_PORT} -o StrictHostKeyChecking=accept-new" \
+            --exclude='.git' \
+            --exclude='.env' \
+            --exclude='config/wazuh_indexer_ssl_certs' \
+            --exclude='tools/misp-mcp-server' \
+            --exclude='.venv' \
+            --exclude='keys' \
+            --exclude='runs' \
+            --exclude='.aptl' \
+            --exclude='node_modules' \
+            ./ "${DEPLOY_USER}@${DEPLOY_HOST}:${DEPLOY_DIR}/"
+
+          # Seed .env from example if first deploy
+          $SSH "cd ${DEPLOY_DIR} && [ -f .env ] || cp .env.example .env"
+
+          # Install Python CLI in venv and start lab
+          $SSH "cd ${DEPLOY_DIR} && ([ -d .venv ] || python3 -m venv .venv) && .venv/bin/pip install -e ."
+          $SSH "cd ${DEPLOY_DIR} && .venv/bin/aptl lab start"
+
+      - name: Verify
+        env:
+          DEPLOY_HOST: ${{ vars.DEPLOY_HOST }}
+          DEPLOY_USER: ${{ vars.DEPLOY_USER }}
+          DEPLOY_DIR: ${{ vars.DEPLOY_DIR || '/opt/aptl' }}
+          DEPLOY_SSH_PORT: ${{ vars.DEPLOY_SSH_PORT || '22' }}
+        run: |
+          SSH="ssh -i ~/.ssh/deploy_key -p ${DEPLOY_SSH_PORT} -o StrictHostKeyChecking=accept-new ${DEPLOY_USER}@${DEPLOY_HOST}"
+
+          # Poll until all containers are running (12 attempts x 10s = 120s max)
+          for attempt in $(seq 1 12); do
+            echo "Verify attempt ${attempt}/12..."
+            RESULT=$($SSH "cd ${DEPLOY_DIR} && docker compose ps --format json" 2>/dev/null || echo "")
+
+            if [ -n "$RESULT" ]; then
+              STATUS=$(echo "$RESULT" | python3 -c "
+          import json, sys
+          containers = []
+          for line in sys.stdin:
+              line = line.strip()
+              if not line: continue
+              try:
+                  if line.startswith('['):
+                      containers.extend(json.loads(line))
+                  else:
+                      containers.append(json.loads(line))
+              except json.JSONDecodeError:
+                  continue
+          if not containers:
+              print('WAITING')
+              sys.exit(0)
+          for c in containers:
+              name = c.get('Name', 'unknown')
+              state = c.get('State', 'unknown')
+              health = c.get('Health', '')
+              info = f'  {name}: {state}'
+              if health: info += f' ({health})'
+              print(info, file=sys.stderr)
+          running = sum(1 for c in containers if c.get('State') == 'running')
+          total = len(containers)
+          print(f'{running}/{total} containers running', file=sys.stderr)
+          if running >= total:
+              print('PASS')
+          else:
+              print('WAITING')
+          ")
+
+              if [ "$STATUS" = "PASS" ]; then
+                echo "All containers running."
+                exit 0
+              fi
+            fi
+
+            echo "Not ready yet, waiting 10s..."
+            sleep 10
+          done
+
+          echo "ERROR: Containers did not all reach running state within 120s"
+          exit 1
+
+      - name: Cleanup SSH key
+        if: always()
+        run: rm -f ~/.ssh/deploy_key

.github/workflows/sonarcloud.yml

@@ -8,22 +8,41 @@ jobs:
   sonarcloud:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev]"
+          pip install -e ".[dev,web]"
       - name: Run tests with coverage
         run: |
           coverage run -m pytest tests/ -q -k "not integration"
           coverage xml -o coverage.xml
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+      - name: Run MCP TypeScript tests with coverage
+        run: |
+          cd mcp/aptl-mcp-common
+          npm install
+          npx vitest run --coverage
+      - name: Run web frontend tests with coverage
+        run: |
+          cd web
+          npm install
+          npx svelte-kit sync
+          npx vitest run --coverage
+          sed -i 's|^SF:|SF:web/|' coverage/lcov.info
       - name: SonarCloud Scan
-        uses: SonarSource/sonarcloud-github-action@v5
+        uses: SonarSource/sonarqube-scan-action@v7
         env:
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+        with:
+          args: >
+            -Dsonar.qualitygate.wait=true

.gitignore

@@ -25,6 +25,8 @@ downloads/
 eggs/
 .eggs/
 lib/
+!web/src/lib/
+!web/tests/lib/
 lib64/
 parts/
 sdist/
@@ -247,6 +249,9 @@ bower_components
 # Compiled binary addons (https://nodejs.org/api/addons.html)
 build/Release
 
+# SvelteKit generated
+.svelte-kit/
+
 # Dependency directories
 node_modules/
 jspm_packages/
@@ -396,4 +401,6 @@ config/wazuh_indexer_ssl_certs/*
 
 notes/
 
+research/
+
 data/

.mcp.json.example

@@ -4,29 +4,29 @@
       "command": "node",
       "args": ["./mcp/mcp-red/build/index.js"],
       "env": {
-        "APTL_TRACE_DIR": "./.aptl/traces"
+        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
       }
     },
     "reverse-sandbox-ssh": {
       "command": "node",
       "args": ["./mcp/mcp-reverse/build/index.js"],
       "env": {
-        "APTL_TRACE_DIR": "./.aptl/traces"
+        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
       }
     },
     "shuffle": {
       "command": "node",
       "args": ["./mcp/mcp-soar/build/index.js"],
       "env": {
-        "APTL_TRACE_DIR": "./.aptl/traces",
+        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318",
         "SHUFFLE_API_KEY": "<run seed-shuffle.sh or check Shuffle UI>"
       }
     },
     "indexer": {
       "command": "node",
       "args": ["./mcp/mcp-indexer/build/index.js"],
       "env": {
-        "APTL_TRACE_DIR": "./.aptl/traces",
+        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318",
         "INDEXER_USERNAME": "admin",
         "INDEXER_PASSWORD": "SecretPassword",
         "API_USERNAME": "wazuh-wui",

.serena/project.yml

@@ -126,3 +126,22 @@ language_backend:
 # list of regex patterns which, when matched, mark a memory entry as read‑only.
 # Extends the list from the global configuration, merging the two lists.
 read_only_memory_patterns: []
+
+# line ending convention to use when writing source files.
+# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
+# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
+line_ending:
+
+# list of regex patterns for memories to completely ignore.
+# Matching memories will not appear in list_memories or activate_project output
+# and cannot be accessed via read_memory or write_memory.
+# To access ignored memory files, use the read_file tool on the raw file path.
+# Extends the list from the global configuration, merging the two lists.
+# Example: ["_archive/.*", "_episodes/.*"]
+ignored_memory_patterns: []
+
+# advanced configuration option allowing to configure language server-specific options.
+# Maps the language key to the options.
+# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
+# No documentation on options means no options are available.
+ls_specific_settings: {}