Implement Docker host integration for selecting codebases as scan targets. Add new API endpoints for listing running Docker containers and retrieving potential code paths from selected containers. Update documentation to reflect new features and security considerations for Docker socket access. Enhance project creation process to allow users to select codebases directly from local Docker containers, improving usability and efficiency.

Author: fr4iser90

docs/platform_plan/02_data_model_and_db_schema.md

@@ -210,7 +210,7 @@ Below are the primary entities that will be represented as Django models. Some n
 `# ... potentially more types ...`
 `ASSET_TYPE_CHOICES = [`
     `(ASSET_TYPE_URL, 'URL'),`
-    `(ASSET_TYPE_GIT, 'Git Repository'),`
+    `(ASSET_TYPE_GIT, 'Git Repository / Codebase Path'),`
     `(ASSET_TYPE_DOCKER, 'Docker Image'),`
     `(ASSET_TYPE_FILE, 'File Upload'),`
     `(ASSET_TYPE_IP, 'IP Address'),`
@@ -224,8 +224,13 @@ Below are the primary entities that will be represented as Django models. Some n
 *   **`asset_type`**: `CharField(max_length=50, choices=ASSET_TYPE_CHOICES, help_text="Type of the asset being targeted.")`
 *   **`identifier`**: `TextField(help_text="The main identifier for the asset (e.g., URL, git clone path, image name).")`
     *   Description: This field stores the core piece of information needed to access/scan the asset.
-*   **`metadata`**: `JSONField(default=dict, blank=True, help_text="Type-specific additional details, e.g., {\"branch\": \"main\"} for git.")`
+        For `asset_type` 'git_repository', this can be a Git URL or a local filesystem path to a codebase.
+        This includes host paths that are derived from inspecting Docker container volumes,
+        allowing direct filesystem scans of codebases running in local containers.
+*   **`metadata`**: `JSONField(default=dict, blank=True, help_text="Type-specific additional details, e.g., {\"branch\": \"main\"} for git, or {\"source_docker_container_id\": \"abcdef123456\", \"source_docker_container_name\": \"my_app_container\", \"path_in_container\": \"/var/www/html\"} if the identifier path was derived from a Docker container volume.")`
     *   Description: Flexible field to store context-specific data for different asset types.
+        For assets derived from Docker containers, this could store the original container ID, name,
+        and the path within the container for traceability or display purposes.
 *   **`description`**: `TextField(blank=True, null=True, help_text="Optional description for this target asset.")`
 *   **`is_active`**: `BooleanField(default=True, help_text="Is this target asset currently active for scanning?")`
 *   **`created_at`**: `DateTimeField(auto_now_add=True)`

docs/platform_plan/03_api_design.md

@@ -22,6 +22,7 @@ This document specifies the design for the SecuLite v2 RESTful API. This API wil
     *   [3.7. Scans (`/api/v1/scans/`)](#37-scans)
     *   [3.8. ScanToolResults (Nested under Scans: `/api/v1/scans/{scan_id}/toolresults/`)](#38-scantoolresults)
     *   [3.9. Findings (`/api/v1/findings/`)](#39-findings)
+    *   [3.10. Docker Host Interaction Endpoints (`/api/v1/dockerhost/`)](#310-docker-host-interaction-endpoints)
     *   *(More resources/endpoints will be detailed here)*
 4.  [Common API Conventions](#4-common-api-conventions)
     *   [4.1. Pagination](#41-pagination)
@@ -534,6 +535,75 @@ Endpoints for viewing, triaging, and managing security findings.
     *   **Description:** To manage comments or an audit trail for a finding. This would likely involve a separate `FindingComment` model.
     *   **Permissions:** `HasAccessToFindingProject` for GET, `CanManageFindingsInProject` for POST.
 
+### 3.10. Docker Host Interaction Endpoints (`/api/v1/dockerhost/`)
+
+These endpoints enable the SecuLite backend (with appropriate permissions and configuration for Docker socket access) to retrieve information about Docker containers running locally on the host. This primarily serves the feature of selecting codebases from Docker volumes as scan targets.
+
+**Prerequisites:**
+- The SecuLite backend must be configured to access the host's Docker socket (see `05_docker_setup.md`).
+- The calling user requires appropriate permissions (e.g., `IsAdminUser` or a more specific permission like `CanAccessDockerHostInfo`).
+
+#### 3.10.1. List Running Docker Containers
+
+*   `GET /api/v1/dockerhost/containers/`
+    *   **Description:** Retrieves a list of Docker containers currently running on the host. The information returned should be relevant for identification and selection in the frontend.
+    *   **Query Params:**
+        *   `name_filter` (string, optional): Filters containers whose names contain the specified string.
+        *   `status_filter` (string, optional, default: 'running'): Filters by container status (e.g., 'running', 'exited').
+    *   **Response Body (200 OK):** Paginated list of Container Information objects.
+        ```json
+        {
+          "count": 1,
+          "next": null,
+          "previous": null,
+          "results": [
+            {
+              "id": "abcdef123456", // Docker Container ID (short or long)
+              "name": "my_application_container_1",
+              "image": "my_app_image:latest",
+              "status": "running", // e.g., 'running', 'exited', 'paused'
+              "created_at": "2023-10-26T10:00:00Z", // Container creation time
+              "ports": [ // Optional: exposed ports for additional info
+                { "host_port": 8080, "container_port": 80, "protocol": "tcp" }
+              ]
+            }
+            // ... other containers
+          ]
+        }
+        ```
+    *   **Permissions:** `IsAdminUser` (or a more specific permission `CanAccessDockerHostInfo`).
+
+#### 3.10.2. Retrieve Potential Code Paths from a Container
+
+*   `GET /api/v1/dockerhost/containers/{container_id}/code-paths/`
+    *   **Description:** For a specific Docker container, retrieves a list of host filesystem paths derived from its volume mounts that could potentially contain codebases. The backend analyzes the container's volume mounts and returns the corresponding host paths.
+    *   **Path Parameter:**
+        *   `container_id` (string, required): The ID of the Docker container.
+    *   **Response Body (200 OK):**
+        ```json
+        {
+          "container_id": "abcdef123456",
+          "container_name": "my_application_container_1",
+          "potential_code_paths": [
+            {
+              "host_path": "/path/on/host/to/volume_for_html",
+              "path_in_container": "/var/www/html",
+              "volume_type": "bind", // 'bind' or 'volume'
+              "description": "Potential codebase (e.g., web server root)" // Optional description
+            },
+            {
+              "host_path": "/another/path/on/host/to/app_code",
+              "path_in_container": "/app/src",
+              "volume_type": "bind",
+              "description": "Potential codebase (e.g., application sources)"
+            }
+            // ... other relevant paths
+          ]
+        }
+        ```
+        If no relevant paths are found or the container has no volumes, `potential_code_paths` will be an empty array.
+    *   **Permissions:** `IsAdminUser` (or `CanAccessDockerHostInfo`).
+
 ---
 
 ## 4. Common API Conventions

docs/platform_plan/04_task_breakdown_phase1.md

@@ -184,4 +184,37 @@ This document outlines the high-level tasks for implementing the SecuLite v2 Min
     -   E12.2.1. Create initial `CHANGELOG.md` or `RELEASE_NOTES.md` file.
     -   E12.2.2. Establish process for updating changelog with each significant change/PR.
 
+## Epic 13: Docker Host Integration for Target Definition (New)
+
+**Goal:** Enable users to select codebases from Docker containers running locally on the server as scan targets.
+
+-   **E13.1. Backend: Docker API Interaction & Configuration**:
+    -   E13.1.1. Add `docker-py` (Python Docker library) to backend dependencies (`pyproject.toml`).
+    -   E13.1.2. Update `docker-compose.yml` to mount the host's Docker socket (`/var/run/docker.sock`) into the backend container (reference: `05_docker_setup.md`). Document security implications.
+    -   E13.1.3. Implement service logic in the backend to list running containers and inspect their volume mounts via the Docker API.
+    -   E13.1.4. Develop and implement heuristics to identify potentially relevant host paths for codebases from volume mounts.
+-   **E13.2. Backend: New API Endpoints for Docker Host Interaction**:
+    -   E13.2.1. Implement API endpoint `/api/v1/dockerhost/containers/` (List Running Docker Containers) as per `03_api_design.md`.
+        -   Include filtering by name and status.
+        -   Ensure endpoint is restricted to authorized users (e.g., Admins).
+    -   E13.2.2. Implement API endpoint `/api/v1/dockerhost/containers/{container_id}/code-paths/` (Retrieve Potential Code Paths) as per `03_api_design.md`.
+        -   Ensure endpoint is restricted to authorized users.
+    -   E13.2.3. Write unit and integration tests for the new API endpoints and Docker interaction logic.
+-   **E13.3. Frontend: UI for Docker Container Selection in Project Creation/Editing**:
+    -   E13.3.1. Design and implement UI elements in `ProjectCreateModal.vue` (or a dedicated component) to:
+        -   Display an option/button to "Select codebase from local Docker container" (visible to authorized users only).
+        -   Display a list of running Docker containers (fetched from the new API endpoint).
+        -   Provide filtering capabilities for the container list.
+    -   E13.3.2. On container selection, implement an API call to fetch potential code paths for that container.
+    -   E13.3.3. Display a selection for the host paths provided by the backend.
+    -   E13.3.4. Populate the selected host path into the project form's "Codebase Path or URL" (`codebase_path_or_url`) field.
+    -   E13.3.5. Store metadata (e.g., container name, path in container) in the `TargetAsset`'s (or project's default configuration) `metadata` field when the project is created.
+-   **E13.4. Frontend: Backend API Integration**:
+    -   E13.4.1. Create API service functions in the frontend to communicate with the new `/api/v1/dockerhost/...` endpoints.
+    -   E13.4.2. Adapt frontend state management (Pinia/Vuex) to handle fetched container and path data if necessary.
+    -   E13.4.3. Implement error handling for API calls.
+-   **E13.5. Documentation & Tests**:
+    -   E13.5.1. Describe the new functionality in user and administrator documentation.
+    -   E13.5.2. Create end-to-end tests for the "create project with codebase from Docker container" workflow (if E2E tests are within MVP scope).
+
 This task breakdown provides a high-level roadmap. Each task will be further broken down into smaller, more manageable sub-tasks and potentially issues in a project tracking system as development commences. 

docs/platform_plan/05_docker_setup.md

@@ -16,6 +16,7 @@ This document details the Docker setup for SecuLite v2, including the services,
     *   [3.7. `nginx` (Web Server/Reverse Proxy) Service](#37-nginx-web-serverreverse-proxy-service)
     *   [3.8. Volumes](#38-volumes)
     *   [3.9. Networks](#39-networks)
+    *   [3.10. Backend Access to the Host Docker Socket (for Container Analysis)](#310-backend-access-to-the-host-docker-socket-for-container-analysis)
 4.  [`backend/Dockerfile` Details](#4-backenddockerfile-details)
 5.  [`backend/entrypoint.sh` Details](#5-backendentrypointsh-details)
 6.  [`frontend/Dockerfile` Details (Multi-stage)](#6-frontenddockerfile-details-multi-stage)
@@ -175,6 +176,8 @@ services:
       - ./backend:/app # Mount backend code for development (live reload)
       - backend_static_collected:/app/staticfiles_collected # Volume for collected static files
       - backend_media_data:/app/media # Volume for user-uploaded media files
+      # NEW: Mount Docker socket
+      - /var/run/docker.sock:/var/run/docker.sock
     ports:
       - "8000:8000"  # Expose Gunicorn port (mainly for Nginx to proxy to)
     env_file:
@@ -205,6 +208,7 @@ services:
     -   `./backend:/app`: Mounts the local `backend` directory into `/app` in the container. This is crucial for development, allowing live code changes without rebuilding the image.
     -   `backend_static_collected:/app/staticfiles_collected`: A named volume for Django's `collectstatic` output. Nginx can potentially serve from this volume.
     -   `backend_media_data:/app/media`: A named volume for user-uploaded files (e.g., `ScanToolResult.raw_output_path`).
+    -   `./var/run/docker.sock:/var/run/docker.sock`: Mounts the Docker socket to allow the backend to interact with Docker.
 -   **`ports: - "8000:8000"`**: Exposes port 8000. While Nginx will be the primary entry point from the outside on port 80/443, this can be useful for direct access during development or if Nginx is on the same host but not in Docker.
 -   **`env_file: - .env`**: Loads environment variables from the `.env` file (e.g., `DJANGO_SECRET_KEY`, `DJANGO_DEBUG`, database URL, Celery settings).
 -   **`depends_on`**: Ensures that the `db` and `redis` services are healthy before this service starts.
@@ -454,6 +458,47 @@ This `networks` definition is also placed at the root level of the `docker-compo
 
 With this, the definition of all services, volumes, and networks for the `docker-compose.yml` file is complete.
 
+### 3.10. Backend Access to the Host Docker Socket (for Container Analysis)
+
+To enable the SecuLite backend to query the list of Docker containers running on the host and analyze their volume paths (as planned for the "Select Docker Container as Scan Target" feature), the `backend` container requires access to the host system's Docker socket.
+
+This is typically achieved by mounting the Docker socket into the `backend` container.
+
+**Update in `docker-compose.yml` for the `backend` service:**
+
+```yaml
+services:
+  # ...
+  backend:
+    build:
+      context: ./backend
+      dockerfile: Dockerfile
+    container_name: seculite_backend
+    # ... other configurations ...
+    volumes:
+      - ./backend:/app
+      - backend_static_collected:/app/staticfiles_collected
+      - backend_media_data:/app/media
+      # NEW: Mount Docker socket
+      - /var/run/docker.sock:/var/run/docker.sock
+    # ...
+```
+
+**Security Implications and Considerations:**
+
+*   **High Privileges:** Access to the Docker socket (`/var/run/docker.sock`) essentially grants the container root-equivalent permissions over the host's Docker daemon. A process within the container with access to this socket can execute arbitrary Docker commands on the host, including starting, stopping, and manipulating containers, as well as accessing the host's file system via volume mounts in newly started containers.
+*   **Risk Mitigation:**
+    *   **Trusted Code:** This functionality should only be implemented if the code accessing the Docker socket (in the SecuLite backend) is absolutely trustworthy and has been carefully vetted.
+    *   **Minimal Usage:** Access to the socket should only be used for explicitly required operations (listing containers, inspecting configurations).
+    *   **No Uncontrolled Command Execution:** The backend should not forward raw, user-supplied commands to the Docker socket.
+    *   **Read-Only Access Preferred:** If possible, only read operations should be performed via the Docker API to retrieve configuration details.
+    *   **Alternative (More Complex):** For environments with higher security requirements, a dedicated, minimally privileged "sidecar" container or an external microservice could be considered to act as a strictly controlled proxy for Docker API requests. However, for the MVP phase of SecuLite v2, direct socket mounting is pursued as a pragmatic approach, assuming SecuLite is operated on a trusted server.
+*   **User in Container:** If the backend process runs as a non-root user within the container, it must be ensured that this user has permission to access the mounted Docker socket. Often, the Docker socket on the host belongs to the `docker` group. The user in the container would then need to be a member of this group (same GID), or the socket would need to be mounted with appropriate permissions, increasing complexity. For the initial implementation, it is assumed that the process in the backend container (still) runs as root or has sufficient permissions. *This is an important point to consider when implementing a non-root user in the backend container.*
+
+**Dependencies:**
+
+*   The `docker-py` (or a similar) Python library must be added to the backend's dependencies (`pyproject.toml`) to interact programmatically with the Docker API.
+
 ---
 
 ## 4. `backend/Dockerfile` Details

docs/platform_plan/09_mvp_epics_user_stories.md

@@ -220,4 +220,31 @@ This document outlines high-level Epics and initial User Stories for the SecuLit
 -   As a new developer joining the project, I want a clear guide on how to set up my local development environment for the MVP.
 -   As a user/stakeholder, I want to see release notes or a changelog for each version of the MVP that is deployed, detailing what has changed.
 
+## Epic 13: Docker Host Integration for Target Definition (New)
+
+**Goal:** Enable authorized users to select codebases from Docker containers running locally on the server as scan targets, simplifying the target definition process.
+
+**Initial User Stories:**
+
+*   **As an Administrator (or authorized user), when creating or editing a project for an application hosted locally on the server via Docker, I want to have an option to select the codebase directly from one of the server's running Docker containers, so I don't have to manually find and copy host paths to the code volumes.**
+    *   *Acceptance Criteria:*
+        *   In the project creation/editing form, a clear option (e.g., button, dropdown trigger) like "Select codebase from local Docker container" is available.
+        *   This option is only visible and usable by users with the appropriate permissions.
+
+*   **As an Administrator (or authorized user), after choosing to select a codebase from a Docker container, I want to see a filterable and searchable list of currently running Docker containers on the server (displaying at least name, ID, and image), so I can quickly identify and select the relevant container.**
+    *   *Acceptance Criteria:*
+        *   The frontend fetches and displays the list of running containers from the backend API.
+        *   The list includes essential identifying information: container name, ID, and image.
+        *   The user can filter or search the list, for example, by container name.
+
+*   **As an Administrator (or authorized user), after selecting a specific Docker container from the list, I want to be presented with a list of potential host filesystem paths that correspond to its volume mounts (especially those typically containing code, like `/var/www/html` or `/app` within the container), so I can choose the correct path to the application's codebase.**
+    *   *Acceptance Criteria:*
+        *   The frontend fetches and displays the relevant host paths for the selected container from the backend API.
+        *   The displayed paths are host paths, ideally with an indication of their corresponding path within the container and volume type.
+
+*   **As an Administrator (or authorized user), after selecting a specific host path (derived from a Docker container's volume), I want this path to be automatically populated into the "Codebase Path or URL" field of the project form, so that the scan can be configured with the correct target.**
+    *   *Acceptance Criteria:*
+        *   The selected host path is correctly entered into the designated form field for the codebase.
+        *   Relevant metadata (e.g., the source Docker container name, the original path within the container) is optionally stored with the target asset information for traceability.
+
 ---