CODITECT Security Profiling Guide

Version: 1.0.0 Last Updated: December 22, 2025 Status: Production Ready

Overview

CODITECT's Dynamic Security Profiling system automatically detects your project's technology stack and generates intelligent command allowlists for enhanced security. Inspired by Auto-Claude's security patterns, this system prevents unauthorized or dangerous commands while allowing legitimate development workflows.

Key Features

Automatic Stack Detection - Detects languages, frameworks, databases, cloud providers, and build tools
Smart Command Allowlists - Generates context-aware command permissions based on detected stack
Custom Script Discovery - Extracts and allows custom scripts from package.json, Makefile, pyproject.toml
Profile Caching - 7-day cache with automatic invalidation on project changes
Command Pattern Matching - Supports wildcard patterns like npm run * and git *
Built-in Safety - Always blocks dangerous system commands (dd, mkfs, shutdown, etc.)

Quick Start

Generate Security Profile

# Generate profile for current project
python3 scripts/stack-detector.py

# Force refresh (ignore cache)
python3 scripts/stack-detector.py --refresh

View Security Profile

# Human-readable output
python3 scripts/stack-detector.py --show

# JSON output
python3 scripts/stack-detector.py --show --json

Check Command Permissions

# Check if command is allowed
python3 scripts/stack-detector.py --check "pytest"
# Output: ALLOWED: pytest
# Exit code: 0

# Check blocked command
python3 scripts/stack-detector.py --check "shutdown -h now"
# Output: BLOCKED: shutdown -h now
# Exit code: 1

# JSON output for programmatic use
python3 scripts/stack-detector.py --check "npm run build" --json
# Output: {"command": "npm run build", "allowed": true}

How It Works

1. Technology Stack Detection

The system scans your project directory for marker files to identify:

Languages:

Python: *.py, requirements.txt, pyproject.toml, setup.py
JavaScript: *.js, package.json
TypeScript: *.ts, tsconfig.json
Rust: *.rs, Cargo.toml
Go: *.go, go.mod
Java: *.java, pom.xml, build.gradle
Ruby: *.rb, Gemfile
PHP: *.php, composer.json
C#: *.cs, *.csproj

Frameworks:

Django: manage.py, settings.py
Flask: app.py, wsgi.py
FastAPI: main.py
React: package.json + src/App.js
Vue: vue.config.js, src/App.vue
Next.js: next.config.js
Express: server.js, app.js

Databases:

PostgreSQL: *.sql, migrations/
MySQL: *.sql, migrations/
SQLite: *.db, *.sqlite
MongoDB: (command-based detection)
Redis: redis.conf

Cloud Providers:

GCP: cloudbuild.yaml, app.yaml
AWS: cloudformation.yaml, template.yaml
Azure: azure-pipelines.yml, host.json

Build Tools:

Make: Makefile
Docker: Dockerfile, docker-compose.yml
Kubernetes: *.yaml, kustomization.yaml

2. Command Allowlist Generation

Based on detected technologies, the system generates an allowlist:

# Python detected → Allow:
python, python3, pip, pip3, pytest, black, mypy, flake8

# Django detected → Allow:
python manage.py *

# Node.js detected → Allow:
node, npm, npx, yarn, jest, eslint, prettier

# React detected → Allow:
npm run *, npx *

3. Custom Script Discovery

Automatically extracts custom scripts from:

package.json:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "test": "jest"
  }
}

→ Allows: npm run dev, npm run build, npm run test

Makefile:

install:
    pip install -r requirements.txt

test:
    pytest tests/

→ Allows: make install, make test

pyproject.toml:

[tool.poetry.scripts]
start = "myapp.main:run"

→ Allows: poetry run start

4. Profile Caching and Invalidation

Profiles are cached for 7 days and automatically invalidated when:

Key project files change (package.json, requirements.txt, etc.)
Profile expiration date is reached
Force refresh is requested (--refresh)

Project hash computation:

hash = SHA256(
    package.json +
    requirements.txt +
    Cargo.toml +
    go.mod +
    Gemfile +
    Makefile +
    ...
)

Profile Schema

Security profiles are stored in .coditect/security-profile.json:

{
  "version": "1.0.0",
  "created_at": "2025-12-22T09:42:01.047584Z",
  "expires_at": "2025-12-29T09:42:01.047883Z",
  "project_hash": "b8c50c4507ffbfb97514c2bbc64083fd893f9e7aaf03766d52b6750d95148f4c",
  "detected_stack": {
    "languages": ["python", "javascript"],
    "frameworks": ["django", "react"],
    "databases": ["postgresql"],
    "cloud_providers": ["gcp"],
    "build_tools": ["docker", "make"],
    "version_control": ["git"],
    "custom_scripts": {
      "package.json": ["dev", "build", "test"],
      "Makefile": ["install", "test", "deploy"]
    }
  },
  "allowed_commands": [
    "python", "python3", "npm", "docker", "make", "git", ...
  ],
  "command_patterns": [
    "npm run *", "make *", "git *", "python manage.py *"
  ],
  "blocked_commands": [
    "dd", "mkfs", "shutdown", "reboot", "halt"
  ]
}

Configuration

Stack detection rules are defined in config/stack-commands.json:

{
  "mappings": {
    "languages": {
      "python": {
        "commands": ["python", "python3", "pip", "pytest", ...],
        "patterns": ["*.py", "requirements.txt", "pyproject.toml"]
      }
    },
    "frameworks": {
      "django": {
        "commands": ["python", "django-admin"],
        "command_patterns": ["python*manage.py*"],
        "patterns": ["manage.py", "settings.py"]
      }
    }
  },
  "always_allowed": ["ls", "pwd", "cat", "grep", ...],
  "always_blocked": ["dd", "mkfs", "shutdown", ...]
}

Adding New Technology Support

To add support for a new language/framework:

Edit config/stack-commands.json
Add entry to appropriate category:

{
  "mappings": {
    "languages": {
      "kotlin": {
        "commands": ["kotlin", "kotlinc", "gradle"],
        "patterns": ["*.kt", "build.gradle.kts"]
      }
    }
  }
}

Regenerate profile:

python3 scripts/stack-detector.py --refresh

Security Best Practices

1. Always Blocked Commands

These commands are always blocked regardless of detected stack:

dd - Disk duplication (can wipe drives)
mkfs - Filesystem creation (can destroy data)
fdisk, parted - Disk partitioning
shutdown, reboot, halt - System power operations

2. Default Allow Policy

Commands not in the allowlist are blocked by default. This whitelist approach ensures:

Only verified commands can execute
Unknown/dangerous commands are rejected
Stack-specific commands are context-aware

3. Pattern Matching Safety

Command patterns use simple prefix matching:

npm run * → Allows npm run build, npm run test
git * → Allows git status, git commit
Patterns are anchored to prevent abuse

4. Profile Validation

Before using a cached profile:

Check expiration date (7-day TTL)
Verify project hash matches current state
Regenerate if validation fails

Integration Examples

Pre-commit Hook

#!/usr/bin/env python3
import sys
from pathlib import Path
from scripts.stack_detector import CoditectStackDetector

# Check if dangerous command in staged files
detector = CoditectStackDetector(Path.cwd(), Path("config/stack-commands.json"))
profile = detector.generate_profile()

# Scan staged shell scripts
for script in staged_shell_scripts:
    with open(script) as f:
        for line in f:
            if not detector.is_command_allowed(line.strip(), profile):
                print(f"ERROR: Blocked command in {script}: {line}")
                sys.exit(1)

CI/CD Validation

# .github/workflows/security.yml
- name: Validate Security Profile
  run: |
    python3 scripts/stack-detector.py --refresh
    python3 scripts/stack-detector.py --show --json > profile.json
    # Upload to security monitoring

IDE Integration

# VS Code extension
def before_terminal_command(command: str):
    detector = CoditectStackDetector(workspace_root, config_path)
    if not detector.is_command_allowed(command):
        show_warning(f"Blocked: {command}")
        return False
    return True

Troubleshooting

Profile Not Generating

Issue: stack-detector.py doesn't detect my stack

Solution:

Verify marker files exist (package.json, requirements.txt, etc.)
Check if files are in project root
Run with --refresh to bypass cache
Add custom patterns to config/stack-commands.json

Command Incorrectly Blocked

Issue: Legitimate command is blocked

Solution:

Check if technology is detected: python3 scripts/stack-detector.py --show
Add technology to config/stack-commands.json
Refresh profile: python3 scripts/stack-detector.py --refresh
Verify: python3 scripts/stack-detector.py --check "your-command"

Profile Not Refreshing

Issue: Changes to project not reflected in profile

Solution:

Key files may not have changed (profile uses hash)
Force refresh: python3 scripts/stack-detector.py --refresh
Check profile expiration: cat .coditect/security-profile.json | grep expires_at

Custom Scripts Not Detected

Issue: Makefile/package.json scripts not allowed

Solution:

Verify file format is valid JSON/Make syntax
Check if files are in project root
View detected scripts: python3 scripts/stack-detector.py --show
Use command patterns: make * in config/stack-commands.json

Advanced Usage

Programmatic API

from pathlib import Path
from scripts.stack_detector import CoditectStackDetector

# Initialize detector
detector = CoditectStackDetector(
    project_root=Path("/path/to/project"),
    config_path=Path("config/stack-commands.json")
)

# Detect stack
stack = detector.detect_all()
print(f"Languages: {stack.languages}")
print(f"Frameworks: {stack.frameworks}")

# Generate profile
profile = detector.generate_profile(force_refresh=False)

# Check command
allowed = detector.is_command_allowed("pytest tests/")
if allowed:
    subprocess.run(["pytest", "tests/"])
else:
    print("Command blocked by security profile")

Custom Validation Logic

def validate_script(script_path: Path, detector: CoditectStackDetector):
    """Validate all commands in a shell script."""
    profile = detector.generate_profile()
    blocked = []

    with open(script_path) as f:
        for i, line in enumerate(f, 1):
            # Extract commands (basic parsing)
            if line.strip() and not line.startswith('#'):
                command = line.split()[0]
                if not detector.is_command_allowed(command, profile):
                    blocked.append((i, command))

    return blocked

Multi-Project Profiles

# Generate profiles for multiple projects
projects = [
    "/path/to/frontend",
    "/path/to/backend",
    "/path/to/ml-service"
]

for project_root in projects:
    detector = CoditectStackDetector(Path(project_root), config_path)
    profile = detector.generate_profile()
    print(f"{project_root}: {len(profile['allowed_commands'])} commands allowed")

FAQ

Q: Does this replace manual code review? A: No. Security profiling is one layer of defense. Always review code and commands manually.

Q: Can I disable security profiling? A: Yes. Simply don't run the stack detector. Profiles are opt-in.

Q: How often should I refresh the profile? A: Automatically refreshes every 7 days or when project files change. Force refresh when adding new dependencies.

Q: Does this work with monorepos? A: Yes. Generate a profile for each sub-project, or use a combined profile at the root.

Q: Can I customize the 7-day expiration? A: Yes. Edit timedelta(days=7) in stack-detector.py line 297.

Q: Are profiles portable across machines? A: No. Profiles are gitignored and machine-local. Each developer generates their own.

Support

Issues: Report bugs or request features via GitHub issues Questions: Check User Troubleshooting first Contributions: See config/stack-commands.json to add new technology support

Last Updated: December 22, 2025 Framework Version: CODITECT v1.7.2 Author: AZ1.AI INC

Overview​

Key Features​

Quick Start​

Generate Security Profile​

View Security Profile​

Check Command Permissions​

How It Works​

1. Technology Stack Detection​

2. Command Allowlist Generation​

3. Custom Script Discovery​

4. Profile Caching and Invalidation​

Profile Schema​

Configuration​

Adding New Technology Support​

Security Best Practices​

1. Always Blocked Commands​

2. Default Allow Policy​

3. Pattern Matching Safety​

4. Profile Validation​

Integration Examples​

Pre-commit Hook​

CI/CD Validation​

IDE Integration​

Troubleshooting​

Profile Not Generating​

Command Incorrectly Blocked​

Profile Not Refreshing​

Custom Scripts Not Detected​

Advanced Usage​

Programmatic API​

Custom Validation Logic​

Multi-Project Profiles​

FAQ​

Related Documentation​

Support​

Overview

Key Features

Quick Start

Generate Security Profile

View Security Profile

Check Command Permissions

How It Works

1. Technology Stack Detection

2. Command Allowlist Generation

3. Custom Script Discovery

4. Profile Caching and Invalidation

Profile Schema

Configuration

Adding New Technology Support

Security Best Practices

1. Always Blocked Commands

2. Default Allow Policy

3. Pattern Matching Safety

4. Profile Validation

Integration Examples

Pre-commit Hook

CI/CD Validation

IDE Integration

Troubleshooting

Profile Not Generating

Command Incorrectly Blocked

Profile Not Refreshing

Custom Scripts Not Detected

Advanced Usage

Programmatic API

Custom Validation Logic

Multi-Project Profiles

FAQ

Related Documentation

Support