Merge branch 'master' into main

Author: kalvinparker

.github/dependabot.yml

@@ -0,0 +1,29 @@
+# .github/dependabot.yml
+#
+# Formal configuration for Dependabot to automate supply chain security.
+
+version: 2
+updates:
+  # 1. Check for updates to the npm dependencies (e.g., @google/gemini-cli)
+  # This ensures our core tool is always patched and up-to-date.
+  - package-ecosystem: "npm"
+    directory: "/" # Location of package.json
+    schedule:
+      interval: "weekly"
+    # Assign reviewers or labels if needed
+    # reviewers:
+    #   - "kalvinparker"
+
+  # 2. Check for updates to the Docker base image (node:22-alpine)
+  # This is critical for patching OS-level vulnerabilities in our container.
+  - package-ecosystem: "docker"
+    directory: "/" # Location of Dockerfile
+    schedule:
+      interval: "daily"
+
+  # 3. Check for updates to our GitHub Actions
+  # This mitigates the risk of vulnerabilities in our CI/CD pipeline itself.
+  - package-ecosystem: "github-actions"
+    directory: "/" # Location of workflow files
+    schedule:
+      interval: "weekly"

.github/workflows/build-and-scan.yml

@@ -0,0 +1,42 @@
+# .github/workflows/build-and-scan.yml
+
+name: Build and Scan Image
+
+# This workflow runs on every push to main and on every pull request
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read # Required to check out the code
+
+jobs:
+  build-and-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      # STEP 1: Build the image and load it into the local runner daemon.
+      # The 'load: true' command is the critical fix.
+      - name: Build and load local image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          load: true
+          # We give it a temporary, predictable tag for the next step.
+          tags: secure-gemini-cli:scan-target
+
+      # STEP 2: Scan the image that was just built and loaded.
+      # This step will now find the image 'secure-gemini-cli:scan-target'.
+      - name: Scan image with Trivy
+        uses: aquasecurity/[email protected]
+        with:
+          image-ref: 'secure-gemini-cli:scan-target'
+          format: 'table'
+          exit-code: '1'
+          ignore-unfixed: true
+          vuln-type: 'os,library'
+          severity: 'CRITICAL,HIGH'

.github/workflows/pr-scan.yml

@@ -1,5 +1,5 @@
 # Start from the official, minimal base image
-FROM node:22-alpine
+FROM node:25-alpine
 
 # Remediate known base-image vulnerabilities (CR-20251013-04)
 RUN apk update && apk upgrade busybox

.github/workflows/release.yml

@@ -13,51 +13,36 @@ This project isn't just a `Dockerfile`; it's a complete, secure software lifecyc
 - ✅ **Hardened Base Image:** Built on `node:22-alpine` and patches OS packages (`apk upgrade`) during the build to mitigate known vulnerabilities.
 - ✅ **Supply Chain Scanned:** Runs `npm audit` as a mandatory, blocking security gate during the Docker build.
 - ✅ **Least Privilege:** Creates and runs as a dedicated, unprivileged `appuser` instead of `root`.
-- ✅ **Continuous Vulnerability Scanning:** A GitHub Actions workflow (`pr-scan.yml`) automatically scans every pull request with Trivy to prevent new vulnerabilities from being merged.
+- ✅ **Continuous Vulnerability Scanning:** A GitHub Actions workflow (`build-and-scan.yml`) automatically scans every pull request with Trivy to prevent new vulnerabilities from being merged.
 - ✅ **Automated Dependency Management:** Dependabot is configured to automatically create pull requests for updates to the base image, `npm` packages, and the CI/CD actions themselves.
 - ✅ **Formal Security Policies:** Includes a `SECURITY.md` file with a clear policy for vulnerability reporting.
 
 ## What is included
 
-- `Dockerfile` — audited build that performs `apk` upgrades, updates `npm`, creates a non-root user, installs dependencies from `package.json`, runs `npm audit`, and sets the `ENTRYPOINT` to `npx gemini`.
-- `package.json` — minimal file with a dependency on `@google/gemini-cli`.
-- **`.github/workflows/`**: Contains two authoritative workflows:
-    - **`pr-scan.yml`**: Builds and scans every pull request.
-    - **`release.yml`**: Securely publishes a new versioned image to a container registry upon the creation of a GitHub Release.
+- **`Dockerfile`**: audited build that performs `apk` upgrades, updates `npm`, creates a non-root user, installs dependencies from `package.json`, runs `npm audit`, and sets the `ENTRYPOINT` to `npx gemini`.
+- **`package.json`**: minimal file with a dependency on `@google/gemini-cli`.
+- **`.github/workflows/`**: Contains one authoritative workflow:
+    - **`build-and-scan.yml`**: Builds and scans every pull request. Securely publishes a new versioned image to a container registry upon the creation of a GitHub Release.
 - **`.github/dependabot.yml`**: Configuration for automated dependency updates.
 - **`SECURITY.md`**: The official security policy for the project.
-```
 
-- The Dockerfile runs `npm audit` during build. In CI you may want to tune the audit policy or run more advanced supply-chain scanning.
-- The image runs as a non-root user. Confirm that any filesystem paths and environment variables used by `gemini` are writable by `appuser`.
-```markdown
+The Dockerfile runs `npm audit` during build. In CI you may want to tune the audit policy or run more advanced supply-chain scanning. The image runs as a non-root user. Confirm that any filesystem paths and environment variables used by `gemini` are writable by `appuser`.
+
 ## Image summary (from last local scan)
 
 - Image: `secure-gemini-cli:latest`
 - OS: alpine 3.22.2
 - Size: ~656.6 MB
 - Trivy scan report (full JSON): `trivy-report.json` (saved in the project root)
 
-Trivy findings (quick summary):
-
-- I parsed and searched the saved `trivy-report.json` in this repository for vulnerability records. No vulnerability objects were found in the report.
-
-Severity counts (from `trivy-report.json`):
-
-- CRITICAL: 0
-- HIGH: 0
-- MEDIUM: 0
-- LOW: 0
-- UNKNOWN: 0
-
 If you'd like a deeper supply-chain audit (for example, run `npm audit` locally and attempt auto-fixes, or re-run Trivy with a different policy), I can add step-by-step remediation guidance. Otherwise this image's saved scan contains no findings to triage.
 
 ## Build locally
 
 Run the following from the `secure-gemini` directory:
 
 ```powershell
-docker build -t secure-gemini-cli:latest .
+docker build -t secure-gemini-cli:latest
 ```
 
 If `npm audit` fails during the Docker build (it may, depending on transient vulnerabilities), you can temporarily allow the build to continue locally by changing the Dockerfile audit step to a non-blocking command (not recommended for CI):
@@ -70,12 +55,16 @@ I recommend addressing audit findings before publishing the image.
 
 ## Run
 
+This image is hosted on GitHub Container Registry (GHCR) and requires a GitHub Personal Access Token (PAT) with the `read:packages` scope for authentication.
+
+**Full instructions on token creation and running the image can be found in [USAGE.md](USAGE.md).**
+
+The final command requires your Gemini API key:
+
 ```powershell
-docker run --rm secure-gemini-cli:latest --help
+docker run -it --rm -e GEMINI_API_KEY="YOUR-GEMINI-API-KEY" secure-gemini-cli:latest
 ```
 
-Because the image uses `npx` as the entrypoint it will run the `gemini` CLI.
-
 ## How to re-run Trivy locally
 
 If you want to re-run the Trivy scan locally (recommended after changes):
@@ -94,10 +83,10 @@ docker run --rm aquasec/trivy:latest image secure-gemini-cli:latest
 
 ## Git / Commit
 
-If you'd like to commit the approved configuration locally, run these PowerShell steps (replace `<your-username>` when adding the remote):
+If you'd like to commit the approved configuration locally, run these PowerShell steps (replace `<folder-location>` and `<your-username>` when adding the remote):
 
 ```powershell
-cd "D:\My Documents\Docker Projects\secure-gemini"
+cd "<folder-location>"
 # create .gitignore if you haven't already
 @"
 node_modules/
@@ -121,13 +110,29 @@ git push -u origin main
 
 ## CI: Build and scan
 
-A GitHub Actions workflow (`.github/workflows/docker-build-scan.yml`) is included to build and scan the image with Trivy on push to `main`. This performs an automated check and can be adjusted to fail the build on specific severities.
+A GitHub Actions workflow (`.github/workflows/build-and-scan.yml`) is included to build and scan the image with Trivy on push to `main`. This performs an automated check and can be adjusted to fail the build on specific severities.
 
-To publish the image from CI (GHCR / Docker Hub), add the appropriate secrets to your repository and enable the `docker-build-scan-publish.yml` workflow. Required secrets for Docker Hub: `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` (or use GHCR with `GITHUB_TOKEN`).
+To publish the image from CI (GHCR / Docker Hub), add the appropriate secrets to your repository and enable the `build-and-scan.yml` workflow. Required secrets for Docker Hub: `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` (or use GHCR with `GITHUB_TOKEN`).
 
 ## Notes
 
 - The Dockerfile runs `npm audit` during build. In CI you may want to tune the audit policy or run more advanced supply-chain scanning.
 - The image runs as a non-root user. Confirm that any filesystem paths and environment variables used by `gemini` are writable by `appuser`.
 
+### Key Milestones Achieved:
+
+    1. Strategy: Shifted from an insecure, ad-hoc installation to a secure, containerised architecture.
+
+    2. Governance: Established a formal SECURITY.md policy, a LICENSE, and README.md documentation.
+
+    3. Hardening: Implemented base image vulnerability patching and least-privilege (non-root) execution.
+
+    4. Supply Chain Security: Integrated mandatory npm audit security gates and a robust `build-and-scan.yml` workflow with Trivy.
+
+    5. Configuration Management: Codified the entire secure build process in a version-controlled Dockerfile and Git repository.
+
+    6. Automation: Deployed a full CI/CD pipeline for secure releases and configured Dependabot for proactive, automated dependency management.
+
+    7. Verification: Successfully validated the entire process with a final, successful local build.
+
 ---

DELETE.md

@@ -1,48 +1,36 @@
 # Security Policy
 
-This document provides the high-level security policy for projects that use the `profile-template` as their base. It is intended to be a canonical, easy-to-find security statement that repository owners can adapt per-repo where necessary.
+This document outlines the security policy for the `secure-gemini` project.
 
 ## Supported Versions
 
-Security support depends on the project's branch or release strategy. Repository maintainers should keep their project's dependencies and CI/CD configurations up to date.
+This project provides a configuration (`Dockerfile`) for building a secure container image. The security of the final image is dependent on the versions of the components at build time. I am committed to keeping the configuration in the `main` branch up-to-date with the latest secure practices.
 
-| Version | Supported |
-| ------- | --------- |
-| `main` (or `master`) branch | :white_check_mark: |
+| Version | Supported          |
+| ------- | ------------------ |
+| `master` branch | :white_check_mark: |
 | Releases (Tags) | :white_check_mark: |
-| Older commits | :x: |
+| Older commits | :x:                |
 
-Users are responsible for pulling the latest changes and rebuilding any artifacts (for example container images) to receive security updates.
+**User Responsibility:** Users are responsible for pulling the latest changes from the `master` branch and rebuilding their images to ensure they have the most recent security patches and dependency versions. My CI/CD pipeline (`pr-scan.yml`) continuously validates the security of the `main` branch.
 
 ## Reporting a Vulnerability
 
-We take security vulnerabilities seriously and prefer coordinated disclosure. Please do not file security reports as public issues.
+I take all security vulnerabilities seriously. I believe in coordinated disclosure and appreciate the community's help in keeping our project secure.
 
-Preferred reporting methods:
+**How to Report a Vulnerability:**
 
-1. Use GitHub's private vulnerability reporting feature (the "Security" tab) when available.
-2. Email the primary maintainer. (Update the email address in the repository's README to a monitored address.)
+Please **DO NOT** report security vulnerabilities through public GitHub issues.
 
-What to expect from us:
+Instead, please report them directly via one of the following methods:
+*   **Primary Method:** Use GitHub's private vulnerability reporting feature, available under the "Security" tab of this repository.
 
-1. Acknowledge receipt within 72 hours.
-2. Provide an initial assessment of impact and validity.
-3. Work on a fix and provide updates until a patch is released.
-4. Coordinate public disclosure after a fix is published.
+**What to Expect:**
 
-## Security responsibilities
+When you report a vulnerability, I will make every effort to:
+1.  Acknowledge receipt of your report within 72 hours.
+2.  Provide an initial assessment of the vulnerability's validity and impact.
+3.  If the vulnerability is accepted, I will work on a fix and aim to release a patch.
+4.  Keep you informed of our progress. I will coordinate with you on the public disclosure of the vulnerability after a fix has been released.
 
-Maintainers should:
-
-- Keep CI workflows (tests, linting, and security scanners) up to date.
-- Regularly update base images and dependencies.
-- Use secret scanning and dependency vulnerability scanning where available.
-- Provide clear instructions for reproducing and verifying fixes.
-
-If you are a contributor or user with security questions, please consult this document and contact the maintainers using the reporting methods above.
-
-## Repository
-
-Repository: `profile-template`
-
-Primary contacts / maintainers: [email protected]
+I am committed to a transparent and timely response. Thank you for helping to keep this project secure.