deepdebug-local-agent 0.3.18 → 1.0.2

package/docs/SECURITY_WHITEPAPER.md

@@ -0,0 +1,249 @@
+# DeepDebug Local Agent - Security Whitepaper
+
+**Version:** 1.0  
+**Date:** February 2026  
+**Classification:** Public
+
+---
+
+## Executive Summary
+
+DeepDebug Local Agent is designed with enterprise security requirements in mind. This document outlines the security architecture, data handling practices, and compliance considerations for organizations evaluating DeepDebug for their development workflows.
+
+---
+
+## 1. Architecture Overview
+
+### 1.1 Deployment Model
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Customer Environment                         │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │                   Local Agent                            │   │
+│  │  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │   │
+│  │  │ Code Reader │────│  Analyzer   │────│ API Client  │  │   │
+│  │  │ (Read-Only) │    │  (Local)    │    │  (HTTPS)    │  │   │
+│  │  └─────────────┘    └─────────────┘    └──────┬──────┘  │   │
+│  └───────────────────────────────────────────────┼──────────┘   │
+│                                                  │               │
+│  ┌───────────────────────────────────────────────┼──────────┐   │
+│  │              Source Code Repositories          │          │   │
+│  │  (Never leaves customer environment)          │          │   │
+│  └───────────────────────────────────────────────┼──────────┘   │
+└──────────────────────────────────────────────────┼──────────────┘
+                                                   │ HTTPS/TLS 1.3
+                                                   ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    DeepDebug Cloud                               │
+│  ┌─────────────────┐    ┌─────────────────┐                     │
+│  │   API Gateway   │────│   AI Analysis   │                     │
+│  │   (Encrypted)   │    │   (Ephemeral)   │                     │
+│  └─────────────────┘    └─────────────────┘                     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 1.2 Key Security Principles
+
+1. **Minimal Data Transfer**: Only relevant code snippets are sent for analysis
+2. **Ephemeral Processing**: Code is processed in memory and not persisted
+3. **Read-Only Access**: Agent only reads source code, never modifies directly
+4. **Encrypted Transit**: All communications use TLS 1.3
+
+---
+
+## 2. Data Handling
+
+### 2.1 What Data is Processed
+
+| Data Type | Stored Locally | Sent to Cloud | Persisted in Cloud |
+|-----------|----------------|---------------|-------------------|
+| Full source code | ✅ Yes | ❌ No | ❌ No |
+| Error snippets (< 500 lines) | ✅ Yes | ✅ Yes (encrypted) | ❌ No |
+| Stack traces | ✅ Yes | ✅ Yes (encrypted) | ❌ No |
+| File paths | ✅ Yes | ⚠️ Anonymized | ❌ No |
+| Fix suggestions | ✅ Yes | ✅ Generated | ⏱️ 24h max |
+| Usage metrics | ❌ No | ✅ Aggregated | ✅ Yes |
+
+### 2.2 Data Retention
+
+- **Code snippets**: Not stored after analysis (ephemeral)
+- **Analysis results**: 24 hours (configurable to 0)
+- **Audit logs**: 90 days (compliance requirement)
+- **Usage metrics**: Aggregated, anonymized, indefinite
+
+### 2.3 Data Residency
+
+Available regions:
+- 🇪🇺 Europe (eu-west-1) - GDPR compliant
+- 🇺🇸 United States (us-east-1)
+- 🇦🇪 Middle East (me-south-1) - Coming Q2 2026
+
+---
+
+## 3. Container Security
+
+### 3.1 Image Security
+
+- **Base Image**: `node:20-alpine` (minimal attack surface)
+- **Non-root User**: Runs as UID 1001
+- **Read-only Filesystem**: Container filesystem is immutable
+- **No Shell Access**: Production images have no shell
+
+### 3.2 Runtime Security
+
+```yaml
+security_opt:
+  - no-new-privileges:true
+read_only: true
+cap_drop:
+  - ALL
+cap_add:
+  - NET_BIND_SERVICE  # Only capability needed
+```
+
+### 3.3 Vulnerability Scanning
+
+- Images scanned with Trivy before release
+- No HIGH or CRITICAL vulnerabilities allowed
+- Weekly automated scans of released images
+- CVE response SLA: 48 hours for CRITICAL
+
+---
+
+## 4. Network Security
+
+### 4.1 Outbound Connections
+
+The agent only connects to:
+
+| Destination | Port | Purpose |
+|------------|------|---------|
+| api.deepdebug.ai | 443 | API communication |
+| (customer git server) | 443/22 | Optional: Git operations |
+
+### 4.2 Inbound Connections
+
+| Port | Purpose | Binding |
+|------|---------|---------|
+| 5055 | Agent API | localhost only (default) |
+
+### 4.3 Firewall Rules
+
+Minimal required rules:
+```
+ALLOW OUTBOUND TCP 443 TO api.deepdebug.ai
+ALLOW INBOUND TCP 5055 FROM localhost (optional)
+```
+
+---
+
+## 5. Authentication & Authorization
+
+### 5.1 Agent Authentication
+
+- API Key per tenant (rotatable)
+- JWT tokens for session management
+- Mutual TLS available for enterprise
+
+### 5.2 User Authentication
+
+- SSO integration (SAML 2.0, OIDC)
+- MFA support
+- RBAC with customizable roles
+
+---
+
+## 6. Compliance
+
+### 6.1 Current Certifications
+
+| Certification | Status | Date |
+|--------------|--------|------|
+| SOC 2 Type I | In Progress | Q2 2026 |
+| SOC 2 Type II | Planned | Q4 2026 |
+| ISO 27001 | Planned | Q1 2027 |
+| GDPR | Compliant | Current |
+
+### 6.2 Compliance Features
+
+- Audit logging (immutable)
+- Data export on request
+- Right to deletion
+- DPA available
+
+---
+
+## 7. Incident Response
+
+### 7.1 Security Incident SLAs
+
+| Severity | Response Time | Resolution Target |
+|----------|--------------|-------------------|
+| Critical | 1 hour | 4 hours |
+| High | 4 hours | 24 hours |
+| Medium | 24 hours | 72 hours |
+| Low | 72 hours | 1 week |
+
+### 7.2 Contact
+
+Security issues: security@deepdebug.ai  
+PGP Key: Available on request
+
+---
+
+## 8. Penetration Testing
+
+- Annual third-party penetration test
+- Continuous automated scanning
+- Bug bounty program (coming Q3 2026)
+
+---
+
+## 9. Enterprise Deployment Options
+
+### 9.1 Cloud (Multi-tenant)
+
+- Shared infrastructure
+- Logical isolation
+- Suitable for: Most organizations
+
+### 9.2 Dedicated Cloud
+
+- Dedicated infrastructure
+- Single-tenant
+- Suitable for: Financial services, healthcare
+
+### 9.3 On-Premise
+
+- Customer-hosted
+- Air-gapped option available
+- Suitable for: Government, defense, highly regulated
+
+---
+
+## 10. FAQ
+
+**Q: Does DeepDebug have access to our full codebase?**  
+A: No. The Local Agent only sends relevant snippets for analysis. Full code never leaves your environment.
+
+**Q: Can we run DeepDebug in an air-gapped environment?**  
+A: Yes. Contact sales for our on-premise deployment option.
+
+**Q: How long is code retained?**  
+A: Code snippets are processed ephemerally and not stored. Analysis results are retained for 24 hours by default (configurable).
+
+**Q: Is DeepDebug GDPR compliant?**  
+A: Yes. We offer EU data residency and full GDPR compliance including DPA.
+
+---
+
+## Contact
+
+**Sales**: sales@deepdebug.ai  
+**Security**: security@deepdebug.ai  
+**Support**: support@deepdebug.ai
+
+---
+
+*This document is subject to change. Last updated: February 2026*

package/env.example

@@ -0,0 +1,41 @@
+# ╔══════════════════════════════════════════════════════════════╗
+# ║       DeepDebug Local Agent - Environment Configuration      ║
+# ╚══════════════════════════════════════════════════════════════╝
+#
+# Copy this file to .env and configure your settings
+#
+# cp .env.example .env
+#
+
+# ─────────────────────────────────────────
+# Required Settings
+# ─────────────────────────────────────────
+
+# Your DeepDebug tenant ID (from dashboard)
+DEEPDEBUG_TENANT_ID=your-tenant-id-here
+
+# Path to your project(s) on the host machine
+PROJECT_PATH=/path/to/your/projects
+
+# ─────────────────────────────────────────
+# Optional Settings
+# ─────────────────────────────────────────
+
+# DeepDebug API URL (change for on-premise)
+DEEPDEBUG_API_URL=https://api.deepdebug.ai
+
+# Agent version to use
+AGENT_VERSION=latest
+
+# Log level (debug, info, warn, error)
+LOG_LEVEL=info
+
+# ─────────────────────────────────────────
+# Enterprise / On-Premise Settings
+# ─────────────────────────────────────────
+
+# For air-gapped environments, point to your internal registry
+# AGENT_IMAGE=your-registry.company.com/deepdebug/local-agent:1.0.0
+
+# For on-premise DeepDebug server
+# DEEPDEBUG_API_URL=https://deepdebug.internal.company.com

package/helm/Chart.yaml

@@ -0,0 +1,17 @@
+apiVersion: v2
+name: deepdebug-agent
+description: DeepDebug Local Agent for enterprise code debugging and analysis
+type: application
+version: 1.0.0
+appVersion: "1.0.0"
+keywords:
+  - debugging
+  - ai
+  - code-analysis
+  - enterprise
+home: https://deepdebug.ai
+sources:
+  - https://github.com/williambella/deepdebug-local-agent
+maintainers:
+  - name: InspTech AI
+    email: support@deepdebug.ai

package/helm/templates/_helpers.tpl

@@ -0,0 +1,60 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "deepdebug-agent.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+*/}}
+{{- define "deepdebug-agent.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "deepdebug-agent.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "deepdebug-agent.labels" -}}
+helm.sh/chart: {{ include "deepdebug-agent.chart" . }}
+{{ include "deepdebug-agent.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "deepdebug-agent.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "deepdebug-agent.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{/*
+Create the name of the service account to use
+*/}}
+{{- define "deepdebug-agent.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "deepdebug-agent.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}

package/helm/templates/deployment.yaml

@@ -0,0 +1,95 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "deepdebug-agent.fullname" . }}
+  labels:
+    {{- include "deepdebug-agent.labels" . | nindent 4 }}
+spec:
+  replicas: {{ .Values.replicaCount }}
+  selector:
+    matchLabels:
+      {{- include "deepdebug-agent.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      annotations:
+        {{- toYaml .Values.podAnnotations | nindent 8 }}
+      labels:
+        {{- include "deepdebug-agent.selectorLabels" . | nindent 8 }}
+    spec:
+      {{- with .Values.image.pullSecrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      serviceAccountName: {{ include "deepdebug-agent.serviceAccountName" . }}
+      securityContext:
+        {{- toYaml .Values.podSecurityContext | nindent 8 }}
+      containers:
+        - name: {{ .Chart.Name }}
+          securityContext:
+            {{- toYaml .Values.securityContext | nindent 12 }}
+          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          ports:
+            - name: http
+              containerPort: 5055
+              protocol: TCP
+          env:
+            - name: NODE_ENV
+              value: "production"
+            - name: PORT
+              value: "5055"
+            - name: DEEPDEBUG_API_URL
+              value: {{ .Values.config.apiUrl | quote }}
+            - name: DEEPDEBUG_TENANT_ID
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "deepdebug-agent.fullname" . }}-secret
+                  key: tenant-id
+            - name: DEEPDEBUG_WORKSPACE_PATH
+              value: {{ .Values.config.workspacePath | quote }}
+            - name: LOG_LEVEL
+              value: {{ .Values.config.logLevel | quote }}
+          livenessProbe:
+            {{- toYaml .Values.livenessProbe | nindent 12 }}
+          readinessProbe:
+            {{- toYaml .Values.readinessProbe | nindent 12 }}
+          resources:
+            {{- toYaml .Values.resources | nindent 12 }}
+          volumeMounts:
+            - name: tmp
+              mountPath: /tmp
+            {{- if .Values.volumes.workspace.enabled }}
+            - name: workspace
+              mountPath: /workspace
+              readOnly: true
+            {{- end }}
+      volumes:
+        - name: tmp
+          emptyDir: {}
+        {{- if .Values.volumes.workspace.enabled }}
+        - name: workspace
+          {{- if .Values.volumes.workspace.persistentVolumeClaim }}
+          persistentVolumeClaim:
+            claimName: {{ .Values.volumes.workspace.persistentVolumeClaim.claimName }}
+          {{- else if .Values.volumes.workspace.hostPath }}
+          hostPath:
+            path: {{ .Values.volumes.workspace.hostPath.path }}
+            type: {{ .Values.volumes.workspace.hostPath.type | default "Directory" }}
+          {{- else if .Values.volumes.workspace.nfs }}
+          nfs:
+            server: {{ .Values.volumes.workspace.nfs.server }}
+            path: {{ .Values.volumes.workspace.nfs.path }}
+          {{- end }}
+        {{- end }}
+      {{- with .Values.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}

package/helm/templates/secret.yaml

@@ -0,0 +1,9 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ include "deepdebug-agent.fullname" . }}-secret
+  labels:
+    {{- include "deepdebug-agent.labels" . | nindent 4 }}
+type: Opaque
+data:
+  tenant-id: {{ .Values.config.tenantId | b64enc | quote }}

package/helm/templates/service.yaml

@@ -0,0 +1,18 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "deepdebug-agent.fullname" . }}
+  labels:
+    {{- include "deepdebug-agent.labels" . | nindent 4 }}
+spec:
+  type: {{ .Values.service.type }}
+  ports:
+    - port: {{ .Values.service.port }}
+      targetPort: http
+      protocol: TCP
+      name: http
+      {{- if and (eq .Values.service.type "NodePort") .Values.service.nodePort }}
+      nodePort: {{ .Values.service.nodePort }}
+      {{- end }}
+  selector:
+    {{- include "deepdebug-agent.selectorLabels" . | nindent 4 }}

package/helm/values.yaml

@@ -0,0 +1,162 @@
+# ╔══════════════════════════════════════════════════════════════╗
+# ║       DeepDebug Local Agent - Helm Chart Values              ║
+# ╚══════════════════════════════════════════════════════════════╝
+#
+# Usage:
+#   helm install deepdebug-agent ./deepdebug-agent -f values.yaml
+#
+
+# ─────────────────────────────────────────
+# Image Configuration
+# ─────────────────────────────────────────
+image:
+  repository: deepdebug/local-agent
+  tag: "1.0.0"
+  pullPolicy: IfNotPresent
+  # For private registries
+  # pullSecrets:
+  #   - name: registry-credentials
+
+# ─────────────────────────────────────────
+# Replica Configuration
+# ─────────────────────────────────────────
+replicaCount: 1
+
+# ─────────────────────────────────────────
+# DeepDebug Configuration
+# ─────────────────────────────────────────
+config:
+  tenantId: ""  # Required: Your tenant ID
+  apiUrl: "https://api.deepdebug.ai"
+  logLevel: "info"
+  
+  # Workspace paths to monitor (mounted via PVC or hostPath)
+  workspacePath: "/workspace"
+
+# ─────────────────────────────────────────
+# Service Configuration
+# ─────────────────────────────────────────
+service:
+  type: ClusterIP
+  port: 5055
+  # For direct access (not recommended in production)
+  # type: NodePort
+  # nodePort: 30055
+
+# ─────────────────────────────────────────
+# Resource Limits
+# ─────────────────────────────────────────
+resources:
+  limits:
+    cpu: "2"
+    memory: "2Gi"
+  requests:
+    cpu: "500m"
+    memory: "512Mi"
+
+# ─────────────────────────────────────────
+# Security Context (Enterprise)
+# ─────────────────────────────────────────
+securityContext:
+  runAsNonRoot: true
+  runAsUser: 1001
+  runAsGroup: 1001
+  fsGroup: 1001
+  readOnlyRootFilesystem: true
+  allowPrivilegeEscalation: false
+  capabilities:
+    drop:
+      - ALL
+
+# ─────────────────────────────────────────
+# Pod Security Context
+# ─────────────────────────────────────────
+podSecurityContext:
+  seccompProfile:
+    type: RuntimeDefault
+
+# ─────────────────────────────────────────
+# Volume Mounts
+# ─────────────────────────────────────────
+volumes:
+  # Workspace volume (configure based on your setup)
+  workspace:
+    # Option 1: PersistentVolumeClaim
+    # persistentVolumeClaim:
+    #   claimName: workspace-pvc
+    
+    # Option 2: HostPath (for development)
+    # hostPath:
+    #   path: /path/to/projects
+    #   type: Directory
+    
+    # Option 3: NFS (enterprise)
+    # nfs:
+    #   server: nfs.company.com
+    #   path: /exports/projects
+    enabled: false
+
+# ─────────────────────────────────────────
+# Health Checks
+# ─────────────────────────────────────────
+livenessProbe:
+  httpGet:
+    path: /health
+    port: 5055
+  initialDelaySeconds: 10
+  periodSeconds: 30
+  timeoutSeconds: 10
+  failureThreshold: 3
+
+readinessProbe:
+  httpGet:
+    path: /health
+    port: 5055
+  initialDelaySeconds: 5
+  periodSeconds: 10
+  timeoutSeconds: 5
+  failureThreshold: 3
+
+# ─────────────────────────────────────────
+# Network Policies (Enterprise)
+# ─────────────────────────────────────────
+networkPolicy:
+  enabled: true
+  # Allow egress only to DeepDebug API
+  egressRules:
+    - to:
+        - ipBlock:
+            cidr: 0.0.0.0/0
+      ports:
+        - protocol: TCP
+          port: 443
+
+# ─────────────────────────────────────────
+# Pod Disruption Budget
+# ─────────────────────────────────────────
+podDisruptionBudget:
+  enabled: false
+  minAvailable: 1
+
+# ─────────────────────────────────────────
+# Service Account
+# ─────────────────────────────────────────
+serviceAccount:
+  create: true
+  name: ""
+  annotations: {}
+
+# ─────────────────────────────────────────
+# Node Selection
+# ─────────────────────────────────────────
+nodeSelector: {}
+tolerations: []
+affinity: {}
+
+# ─────────────────────────────────────────
+# Annotations
+# ─────────────────────────────────────────
+podAnnotations:
+  prometheus.io/scrape: "true"
+  prometheus.io/port: "5055"
+  prometheus.io/path: "/metrics"