#Author: Miker Seetoo #No I will not be changing the name

CodeSecs Documentation

CodeSecs is a zero-dependency, DevSecOps automation tool designed to analyze Git diffs and generate artifacts. By hooking directly into local LLMs or cloud providers, it automates code reviews, technical documentation updates, security vulnerability tracking, and dynamic risk scoring before code hits your production pipeline.

Architecture

1. Installation

Install the package into your project as a development dependency:

npm install --save-dev codesecs

Or you can run commands directly without a persistent installation using npx:

npx codesecs --help

2. Initialization

Generate a fresh template configuration file in the root directory of your project:

npx codesecs init

This creates a codesecs.config.json file.

Configuration (codesecs.config.json)

The config file manages your connection strings, controls which automated tasks execute, and allows you to rewrite the base system prompt instructions to your liking.

{
  "apiKey": "",
  "baseUrl": "https://api.openai.com/v1",
  "model": "gpt-4o-mini",
  "outputDir": "artifacts",
  "tasks": [
    "docs",
    "review",
    "security"
  ],
  "plugins": [],
  "prompts": {
    "docs": "Generate technical docs for changed code",
    "review": "Review for bugs, maintainability, performance, and logic errors.",
    "security": "Perform devsecops review focusing on secrets, auth, injection, and insecure config."
  }
}

Environment Overrides

To protect secrets or dynamically configure pipelines, CodeSecs prioritizes environment variables over standard JSON properties:

| JSON Key | Environment Variable | Purpose | | --- | --- | --- | | apiKey | AI_API_KEY | Bearer Token authentication credential | | baseUrl | AI_BASE_URL | Destination host URI path for API endpoint calls | | model | AI_MODEL | Explicit text generation model identifier | | outputDir | SECS_OUTPUT_DIR | Name of the local output workspace directory |

CLI Commmands

CodeSecs includes an expressive CLI to drive individual tasks or run unified evaluations.

codesecs run

Analyzes your current local Git changes (prioritizing staged files, fallback to your last commit) and simultaneously runs all active background validation jobs.

npx codesecs run

codesecs init

This will initialize the default codesecs.config.json file

npx codesecs init

codesecs doctor

This will show you the env variables you have initialized

npx codesecs doctor

codesecs serve

This will launch a server on localhost:4321 with a dashboard of your CODESecS artifacts. This is still a work in progress.

npx codesecs serve

codesecs compare [base] [head]

Explicitly focuses the AI evaluation on changes strictly occurring between two specified branches, commits, or tags.

npx codesecs compare main feature-branch

codesecs review-pr <provider> <repo_id> <pr_id>

Executes code evaluation against your active codebase changes and directly posts a summary comment to your pull request/merge request thread.

• Supported Providers: github | gitlab

npx codesecs review-pr github octocat/hello-world 42

codesecs document

Runs the document function individually. Generates an ai-doc.md

npx codesecs document

codesecs risk

Runs the risk report individually. Generates risk-report.json

npx codesecs risk

codesecs security

Runs security check individually. Generates ai-security-report.md

npx codesecs security

codesecs review

Runs review function individually. Generates ai-pr-review.md

npx codesecs review

codesecs --help

Take a guess

npx codesecs --help

Generated Artifacts

When executing codesecs run, the workspace builds isolated files inside your assigned output directory (defaulting to ./artifacts):

• changed-files.txt: A clean, newline-separated catalog of target source files parsed.
• ai-docs.md: Freshly structured developer documentation capturing functional architectural adjustments.
• ai-pr-review.md: Pragmatic peer review logging code quality findings, structural feedback, and optimizations.
• ai-security-report.md: Meticulous DevSecOps threat assessment searching for vulnerabilities, injection vectors, or leaked credentials.
• risk-score.json: Structural metadata parsing code impact strictly conforming to this scheme:

{
  "score": 35,
  "summary": "Mild refactor introducing standard error handling logic.",
  "highlights": ["Adds comprehensive try/catch blocks to core data router"]
}

Testing Locally via Ollama

You can completely detach CodeSecs from proprietary models and run your DevSecOps pipeline entirely on your local machine for zero cost with Ollama.

1. Boot up Ollama locally and fetch a small model explicitly tuned for code analysis:

ollama pull qwen2.5-coder:1.5b

2. Run CodeSecs by passing variables targeting your local engine instance:

AI_API_KEY="local-bypass" \
AI_BASE_URL="http://localhost:11434/v1" \
AI_MODEL="gemma4" \
npx codesecs run

CI/CD Integration (GitHub Actions)

Add CodeSecs into your testing suite using local CPU-bound workflows to validate commits automatically without exposing API keys:

name: CodeSecs

on:
  pull_request:
    branches: [ main ]

jobs:
  security-audit:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Essential to compute accurate git diff targets

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Setup Ollama
        uses: ai-action/setup-ollama@v2

      - name: Pull Evaluation Model
        run: ollama pull gemma4

      - name: Run CodeSecs Pipeline
        env:
          AI_API_KEY: "ollama-bypass"
          AI_BASE_URL: "http://localhost:11434/v1"
          AI_MODEL: "gemma4"
          SECS_OUTPUT_DIR: "devsecops-artifacts"
        run: |
          npm ci
          npx codesecs run
        
      - name: Archive DevSecOps Build Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: devsecops-ai-reports
          path: devsecops-artifacts/
          retention-days: 14

flowchart TD
    Trigger((Pull Request <br/> to 'main')) --> Job[Job: security-audit <br/> Environment: ubuntu-latest]
    
    subgraph Execution Steps
        direction TB
        Job --> S1[Checkout Repository <br/> actions/checkout@v4]
        S1 --> S2[Setup Node.js <br/> Version 20]
        S2 --> S3[Setup Ollama <br/> ai-action/setup-ollama@v2]
        S3 --> S4[Pull Evaluation Model <br/> gemma4]
        S4 --> S5[Run CodeSecs Pipeline <br/> npm ci & npx codesecs run]
        S5 --> S6[Archive Artifacts <br/> actions/upload-artifact@v4]
    end

    %% Additional Context / Environment details
    S5 -. Injects Env Vars .-> Env[AI_API_KEY <br/> AI_BASE_URL <br/> AI_MODEL <br/> SECS_OUTPUT_DIR]
    S6 -. Saves Path .-> Art[devsecops-artifacts/ <br/> Retention: 14 days]

CI/CD Integration (GitLab Pipeline)

stages:
  - test

variables:
  AI_API_KEY: "ollama-bypass"
  AI_BASE_URL: "http://localhost:11434/v1"
  AI_MODEL: "gemma3"
  SECS_OUTPUT_DIR: "devsecops-artifacts"

security-audit:
  stage: test
  image: node:20  # Node 20 provides the environment for npx
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "main"'
  before_script:
    - apt-get update && apt-get install -y zstd curl
    - curl -fsSL https://ollama.com/install.sh | sh
    - ollama serve &
    - sleep 5
    - ollama pull gemma3
  script:
    - npx codesecs run
  artifacts:
    name: "devsecops-ai-reports"
    paths:
      - devsecops-artifacts/
    expire_in: 14 days

flowchart TD
    Trigger((Merge Request Event <br/> Target Branch: 'main')) --> Job[Job: security-audit <br/> Image: node:20]
    
    subgraph Execution Steps
        direction TB
        Job --> S1[before_script: <br/> Install curl & zstd]
        S1 --> S2[Install Ollama <br/> via install.sh]
        S2 --> S3[Start Ollama <br/> ollama serve &]
        S3 --> S4[Pull Evaluation Model <br/> ollama pull gemma3]
        S4 --> S5[script: <br/> npx codesecs run]
        S5 --> S6[Upload Artifacts <br/> devsecops-artifacts/]
    end

    %% Pipeline Variables and Artifact Retention
    S5 -. Injects Variables .-> Var[AI_API_KEY <br/> AI_BASE_URL <br/> AI_MODEL <br/> SECS_OUTPUT_DIR]
    S6 -. Saves Path .-> Art[devsecops-artifacts/ <br/> Expire: 14 days]

CI/CD Integration (Env Variables)

If you want to use your own model, just set your keys in the codesecs.config.json. You can also set the variables in your CI/CD settings. Use the following naming convention

AI_API_KEY AI_BASE_URL AI_MODEL

The package will default to these env variables over whatever you have in your codesecs.config.json

stages:
  - test
variables:
  SECS_OUTPUT_DIR: "devsecops-artifacts"

security-audit:
  stage: test
  image: node:20  # Node 20 provides the environment for npx
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "main"'
  script:
    - npx codesecs run
  artifacts:
    name: "devsecops-ai-reports"
    paths:
      - devsecops-artifacts/
    expire_in: 14 days

flowchart TD
    Trigger((Merge Request Event <br/> Target Branch: 'main')) --> Job[Job: security-audit <br/> Image: node:20]
    
    subgraph GitLab CI/CD Runtime
        Job --> RunScript[script: <br/> npx codesecs run]
    end

    subgraph Config Resolution Logic [How CodeSecs Decides Which Config to Use]
        RunScript --> CheckEnv{Are Env Variables Set? <br/> AI_API_KEY <br/> AI_BASE_URL <br/> AI_MODEL}
        
        CheckEnv -- Yes --> UseEnv[Priority 1: Environment Variables <br/> Override config file values]
        CheckEnv -- No --> UseConfig[Priority 2: codesecs.config.json <br/> Fallback to local defined values]
    end

    subgraph Outputs
        UseEnv --> Exec[Execute Security Audit]
        UseConfig --> Exec
        Exec --> S2[Upload Artifacts <br/> devsecops-artifacts/]
    end

    S2 -. Saves Path .-> Art[devsecops-artifacts/ <br/> Expire: 14 days]

Custom Plugins

CodeSecs features an extensible runtime wrapper allowing you to run bespoke logic right alongside the core engine. To design a plugin, export an default object matching the runtime interface structure:

// plugins/license-check.js
import fs from 'node:fs';
import path from 'node:path';

export default {
    name: "license-check",
    async run({ diff, changedFiles, outputDir }) {
        // Custom verification checking for restricted dependency ingestion
        if (diff.includes("gpl-3.0")) {
             fs.writeFileSync(
                 path.join(outputDir, "plugin-license-alert.txt"), 
                 "ALERT: GPL-3.0 string sequence detected inside incoming code modifications."
             );
        }
    }
};

Register the file inside your codesecs.config.json array:

"plugins": [
  "./plugins/license-check.js"
]