Add Darkwing security scan results and remediation artifacts

Security scan completed on 2026-09-08, documenting findings and proposed fixes for attack surface review.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

darkwing-fixes.patch

@@ -0,0 +1,218 @@
+diff --git a/shopdb/__init__.py b/shopdb/__init__.py
+index 1234567..abcdefg 100644
+--- a/shopdb/__init__.py
++++ b/shopdb/__init__.py
+@@ -204,6 +204,27 @@ def create_app(config_name: str = None) -> Flask:
+
+     # Initialize plugin manager
+     with app.app_context():
++        # On first run (no users exist), log the setup token so the operator can
++        # create the first admin. The token gates POST /api/setup/create-admin to
++        # prevent a network race during the install window (API starts serving
++        # before the admin exists in every documented deploy path).
++        from shopdb.core.models import User
++        try:
++            if User.query.count() == 0:
++                token = app.config.get('SETUP_TOKEN') or os.environ.get('SETUP_TOKEN')
++                if token:
++                    app.logger.warning('=' * 60)
++                    app.logger.warning('FIRST RUN: No users exist.')
++                    app.logger.warning('Setup token: %s', token)
++                    app.logger.warning('Create admin: POST /api/setup/create-admin')
++                    app.logger.warning('  with header: X-Setup-Token: <token>')
++                    app.logger.warning('OR use CLI: docker exec shopdb-api flask seed admin')
++                    app.logger.warning('=' * 60)
++                else:
++                    app.logger.warning('FIRST RUN: No users exist, no SETUP_TOKEN set.')
++                    app.logger.warning('Use CLI: docker exec shopdb-api flask seed admin')
++        except Exception:
++            pass  # DB not ready yet, skip
+         plugin_manager.init_app(app, db)
+
+     # Register core blueprints
+diff --git a/shopdb/cli/__init__.py b/shopdb/cli/__init__.py
+index 2345678..bcdefgh 100644
+--- a/shopdb/cli/__init__.py
++++ b/shopdb/cli/__init__.py
+@@ -196,6 +196,30 @@ def drop_all():
+ @click.group('seed')
+ def seed_cli():
+     """Database seeding commands."""
+     pass
+
+
++@seed_cli.command('show-setup-token')
++@with_appcontext
++def show_setup_token():
++    """Display the setup token for first-admin creation.
++
++    The token gates POST /api/setup/create-admin so a network race cannot claim
++    the instance during the install window. Printed at first startup; retrieve
++    it here if the logs rotated or you lost the terminal.
++    """
++    import os
++    from flask import current_app
++    from shopdb.core.models import User
++
++    if User.query.count() > 0:
++        click.echo(click.style("Setup already complete (users exist).", fg='green'))
++        return
++
++    token = current_app.config.get('SETUP_TOKEN') or os.environ.get('SETUP_TOKEN')
++    if token:
++        click.echo(click.style("Setup token: ", fg='cyan') + token)
++        click.echo("Use: curl -X POST .../api/setup/create-admin -H 'X-Setup-Token: <token>' ...")
++    else:
++        click.echo(click.style("No SETUP_TOKEN configured.", fg='yellow'))
++        click.echo("Use 'flask seed admin' from inside the container (no token needed).")
++
++
+ @seed_cli.command('admin')
+diff --git a/shopdb/core/api/setup.py b/shopdb/core/api/setup.py
+index 3456789..cdefghi 100644
+--- a/shopdb/core/api/setup.py
++++ b/shopdb/core/api/setup.py
+@@ -5,6 +5,10 @@ per-plugin maps. The first-admin account, setup-complete flag, site identity,
+ plugin, and map configuration reuse the existing settings / plugins APIs.
+ """
+
++import hmac
++import ipaddress
++import os
++
+ from flask import Blueprint, request, current_app
+ from flask_jwt_extended import jwt_required
+ from werkzeug.security import generate_password_hash
+@@ -29,6 +33,45 @@ __all__ = [
+ ]
+
+
++# Minimum length for the bootstrap administrator password. 12 characters is the
++# shortest length that still resists offline cracking of a single leaked hash.
++MIN_ADMIN_PASSWORD_LENGTH = 12
++
++
++def _is_loopback(addr):
++    """True when the request originated on the machine running the API."""
++    if not addr:
++        return False
++    try:
++        return ipaddress.ip_address(addr.split('%')[0]).is_loopback
++    except ValueError:
++        return False
++
++
++def _bootstrap_allowed():
++    """Proof of operator control for first-admin creation.
++
++    An empty users table is an ordering condition, not authorization: the API
++    serves requests before the first account exists on every fresh deploy, so a
++    remote caller could otherwise claim the instance during the install window.
++    Require either the one-time setup token (SETUP_TOKEN in config or the
++    environment, presented as the X-Setup-Token header) or a request coming from
++    loopback, i.e. the host the operator is installing on.
++    """
++    token = str(current_app.config.get('SETUP_TOKEN')
++                or os.environ.get('SETUP_TOKEN') or '').strip()
++    if token:
++        supplied = (request.headers.get('X-Setup-Token') or '').strip()
++        return bool(supplied) and hmac.compare_digest(supplied, token)
++    return _is_loopback(request.remote_addr)
++
++
++def _setup_already_complete():
++    """setup_complete is written once the wizard finishes; treat it as final."""
++    row = Setting.query.filter_by(key='setup_complete').first()
++    return bool(row) and str(row.value).strip().lower() in ('true', '1', 'yes')
++
++
+ @setup_bp.route('/needs-admin', methods=['GET'])
+ def needs_admin():
+     """True when no users exist yet - the app's very first run. Public so the
+@@ -38,17 +81,29 @@ def needs_admin():
+
+ @setup_bp.route('/create-admin', methods=['POST'])
+ def create_admin():
+-    """Create the first admin. Only works while there are zero users, so it
+-    can't be abused after setup. No auth (there is no one to auth as yet)."""
+-    if User.query.count() > 0:
++    """Create the first admin. Only works while there are zero users, setup has
++    not been marked complete, and the caller proves operator control (setup
++    token or a loopback request)."""
++    if User.query.count() > 0 or _setup_already_complete():
+         return error_response(ErrorCodes.FORBIDDEN,
+                               'An account already exists; sign in instead.', http_code=403)
++    if not _bootstrap_allowed():
++        return error_response(
++            ErrorCodes.FORBIDDEN,
++            'First-admin creation requires the setup token (X-Setup-Token) '
++            'or a request from the server itself.',
++            http_code=403)
+     data = request.get_json() or {}
+     username = (data.get('username') or '').strip()
+     email = (data.get('email') or '').strip()
+     password = data.get('password') or ''
+     if not (username and email and password):
+         return error_response(ErrorCodes.VALIDATION_ERROR,
+                               'username, email and password are required')
++    if len(password) < MIN_ADMIN_PASSWORD_LENGTH:
++        return error_response(
++            ErrorCodes.VALIDATION_ERROR,
++            f'password must be at least {MIN_ADMIN_PASSWORD_LENGTH} characters')
+
+     admin_role = Role.query.filter_by(rolename='admin').first()
+     if not admin_role:
+@@ -61,4 +116,6 @@ def create_admin():
+     user.roles.append(admin_role)
+     db.session.add(user)
+     db.session.commit()
++    current_app.logger.warning('First administrator %r created from %s',
++                               username, request.remote_addr)
+     return success_response({'username': username}, message='Admin created', http_code=201)
+diff --git a/plugins/knowledgebase/api/routes.py b/plugins/knowledgebase/api/routes.py
+index 4567890..defghij 100644
+--- a/plugins/knowledgebase/api/routes.py
++++ b/plugins/knowledgebase/api/routes.py
+@@ -1,7 +1,6 @@
+ """Knowledge Base API endpoints."""
+
+ from flask import Blueprint, request
+-from flask_jwt_extended import jwt_required
+
+ from shopdb.api import (
+     intarg,
+@@ -180,19 +179,27 @@ def get_article(link_id: int):
+
+
+ @knowledgebase_bp.route('/<int:link_id>/click', methods=['POST'])
+-@jwt_required(optional=True)
++@require_permission('kb.view')
+ def track_click(link_id: int):
+-    """Increment click counter and return the URL to redirect to."""
+-    article = db.session.get(KnowledgeBase, link_id)
++    """Increment the click counter for an article the caller is allowed to read.
+
+-    if not article or not article.isactive:
++    Gated on kb.view like every other read of this table: an anonymous caller
++    walking link ids must not be able to probe which articles exist, drive the
++    counters that order the list, or spend a DB transaction per request.
++
++    Restricted to the same visible set as the list/detail reads so an article
++    about a retired application is not reachable here either.
++
++    The linkurl is deliberately not echoed back: whoever is permitted to click
++    already received it in the list or detail response the click came from.
++    """
++    article = _visible_articles().filter(KnowledgeBase.linkid == link_id).first()
++
++    if not article:
+         return error_response(ErrorCodes.NOT_FOUND, 'Article not found', http_code=404)
+
+     article.increment_clicks()
+     db.session.commit()
+
+-    return success_response({
+-        'linkurl': article.linkurl,
+-        'clicks': article.clicks
+-    })
++    return success_response({'clicks': article.clicks})