defendr

name	defendr
description	[WHAT] 4-layer security scanner for untrusted code: static analysis, malware/CVE scanning, Docker sandbox, agentic review. [HOW] Orchestrates rg patterns, ClamAV, pip-audit, osv-scanner, semgrep, Docker strace, and LLM code review. [WHEN] Before running cloned repos, installing pip/npm packages, intake of external code, pre-commit on untrusted PRs, workshop evaluation. [WHY] Agents clone and execute code from the internet. One malicious setup.py and your machine is owned. Triggers: "security scan", "malware scan", "defendr", "scan for malware", "virus scan", "supply chain", "is this safe", "scan this repo", "audit dependencies", "sandbox", "before running", "untrusted code"
skill_type	leaf
version	1.0.0

Defendr — 4-Layer Security Scanner

Run all 4 layers in order. Stop and flag on any critical finding.

Layer 1: Static Pattern Analysis

No tools needed. Uses rg (ripgrep). Run this FIRST on raw source before any install.

Supply Chain (setup.py / pyproject.toml / package.json)

# Code execution in install scripts
rg --glob '**/setup.py' -n 'os\.system\(|subprocess\.(call|run|Popen)\(|eval\(|exec\(' TARGET_DIR

# Custom build backends (not setuptools/flit/poetry/hatch)
rg --glob '**/pyproject.toml' -n 'build-backend.*=.*(?!setuptools|flit|poetry|hatch|maturin)' TARGET_DIR

# npm install hooks
rg --glob '**/package.json' -n '"(pre|post)install"\s*:\s*"' TARGET_DIR

# curl|sh pattern
rg --glob '**/{Makefile,*.sh,install*}' -n 'curl\s.*\|\s*(sh|bash)|wget\s.*\|\s*(sh|bash)' TARGET_DIR

# Dynamic imports in setup
rg --glob '**/setup.py' -n '__import__\(' TARGET_DIR

Obfuscation

# Base64 decode + exec (classic payload delivery)
rg -n 'base64\.(b64)?decode.*exec|exec.*base64\.(b64)?decode' TARGET_DIR

# Hex-encoded or rot13 strings
rg -n '\\x[0-9a-f]{2}\\x[0-9a-f]{2}\\x[0-9a-f]{2}|codecs\.decode\(.*rot13' TARGET_DIR

# Eval with constructed string
rg -n 'eval\(\s*['"'"'"].*['"'"'"]\s*\+|eval\(\s*chr\(|eval\(\s*"\\x' TARGET_DIR

# JavaScript packer
rg --glob '**/*.js' -n 'eval\(function\(p,a,c,k,e,[rd]\)' TARGET_DIR

Network / Reverse Shells

# Reverse shell patterns
rg -n '/bin/sh\s+-i|socket\.connect.*\d+\.\d+\.\d+\.\d+|nc\s+-e\s+/bin|bash\s+-c\s.*dev/tcp' TARGET_DIR

# HTTP POST to hardcoded IP
rg --glob '**/*.py' -n 'requests\.(post|put)\(['"'"'"]https?://\d+\.\d+\.\d+\.\d+' TARGET_DIR

# DNS exfiltration
rg --glob '**/*.py' -n 'socket\.getaddrinfo\(.*\+.*\+|\.encode\(\)\.hex\(\).*resolve' TARGET_DIR

Hardcoded Secrets

# API keys / tokens
rg -n '['"'"'"](?:sk-|ak-|AKIA|ghp_|gho_|github_pat_)[a-zA-Z0-9]{20,}['"'"'"]' TARGET_DIR

# Private keys
rg -n '-----BEGIN (RSA |EC |DSA )?PRIVATE KEY-----' TARGET_DIR

# AWS access keys
rg -n 'AKIA[0-9A-Z]{16}' TARGET_DIR

Prompt Injection

# LLM prompt injection in source/docs
rg -i -n 'ignore\s+(all\s+)?previous\s+instructions|you\s+are\s+now\s+a|system\s*:\s*you\s+are' TARGET_DIR

# Hidden instructions in HTML/Markdown comments
rg -i --glob '**/*.{md,html}' -n '<!--.*(?:ignore|override|bypass|admin|sudo|root|secret).*-->' TARGET_DIR

Verdict: Any match in setup.py/pyproject.toml = STOP. Review manually. Matches in application code = flag and continue to Layer 2.

Layer 2: Tool-Based Scanning

Install these tools, then scan.

ClamAV (malware signatures)

# Install (one-time)
brew install clamav
cd /opt/homebrew/etc/clamav/
cp freshclam.conf.sample freshclam.conf
sed -i '' 's/^Example/#Example/' freshclam.conf
freshclam    # Downloads ~300MB virus definitions

# Scan
clamscan -r --infected --no-summary TARGET_DIR
# Exit code 1 = virus found. Any "FOUND" line = STOP.

pip-audit (Python CVEs)

# Install
pip install pip-audit

# Scan requirements.txt
pip-audit --requirement TARGET_DIR/requirements.txt --format json

# Scan installed venv
pip-audit --format json

osv-scanner (multi-ecosystem CVEs)

# Install
brew install osv-scanner

# Scan (recursive, all ecosystems)
osv-scanner --format json -r TARGET_DIR

semgrep (SAST rules)

# Install
pip install semgrep

# Scan with auto rules
semgrep --config auto --json TARGET_DIR

Check tool availability

command -v clamscan && echo "ClamAV: ready" || echo "ClamAV: MISSING — brew install clamav && freshclam"
command -v pip-audit && echo "pip-audit: ready" || echo "pip-audit: MISSING — pip install pip-audit"
command -v osv-scanner && echo "osv-scanner: ready" || echo "osv-scanner: MISSING — brew install osv-scanner"
command -v semgrep && echo "semgrep: ready" || echo "semgrep: MISSING — pip install semgrep"

Verdict: ClamAV FOUND = STOP. Critical CVEs with no fix = flag. High CVEs = warn and continue.

Layer 3: Docker Sandbox

Install deps inside an isolated container. Monitor syscalls. No network access.

Build the sandbox

# Create scan container (one-time, reusable)
docker run -d \
  --name defendr-sandbox \
  --network none \
  --memory 512m \
  --cpus 1.0 \
  --read-only \
  --tmpfs /tmp:rw,size=256m \
  --tmpfs /root:rw,size=64m \
  -v "$(pwd)/TARGET_DIR:/scan:ro" \
  python:3.12-slim \
  sleep infinity

# Or reuse existing
docker start defendr-sandbox 2>/dev/null || echo "create it first"

Run sandboxed install with strace

docker exec defendr-sandbox bash -c '
  apt-get update -qq && apt-get install -y -qq strace >/dev/null 2>&1
  cd /scan
  if [ -f requirements.txt ]; then
    strace -f -e trace=network,open,connect -o /tmp/trace.log \
      pip install --no-cache-dir -r requirements.txt 2>&1
  elif [ -f setup.py ] || [ -f pyproject.toml ]; then
    strace -f -e trace=network,open,connect -o /tmp/trace.log \
      pip install --no-cache-dir . 2>&1
  fi

  echo "=== SUSPICIOUS FILE ACCESS ==="
  grep -E "open.*(etc/passwd|etc/shadow|\.ssh/|\.aws/|\.config/)" /tmp/trace.log 2>/dev/null || echo "none"

  echo "=== NETWORK CALLS ==="
  grep -c "connect(" /tmp/trace.log 2>/dev/null || echo "0"

  echo "=== NON-TEMP FILE WRITES ==="
  grep "O_WRONLY\|O_CREAT" /tmp/trace.log | grep -v "/tmp\|/proc\|__pycache__\|\.pyc" | head -20
'

Cleanup

docker stop defendr-sandbox && docker rm defendr-sandbox

Verdict: Any access to /etc/passwd, /.ssh/, /.aws/ = CRITICAL. Network calls during install with --network=none = suspicious (should fail silently). Non-temp file writes outside package dirs = flag.

Layer 4: Agentic Review

After Layers 1-3, if findings exist, review the flagged files with an LLM.

What to review

Feed each flagged file to the LLM with this prompt:

You are a security auditor. This file was flagged by automated scanning.

File: {path}
Flag: {rule_id} — {description}
Matched line: {match}

Analyze this file for:
1. Is this a genuine security risk or a false positive?
2. If genuine: what is the attack vector?
3. If false positive: explain why the pattern matched but is safe.
4. Severity: critical / high / medium / low / false-positive

Respond with a structured verdict.

Decision matrix

Layer 1	Layer 2	Layer 3	Layer 4	Verdict
clean	clean	clean	—	SAFE — proceed
flags	clean	clean	false-positive	SAFE — proceed
flags	clean	clean	genuine	BLOCK — do not execute
clean	CVEs	clean	—	WARN — update deps
any	FOUND	any	—	BLOCK — malware detected
any	any	suspicious	genuine	BLOCK — behavioral threat

Quick Run (All 4 Layers)

TARGET=poc/osint/username-search/sherlock

echo "=== LAYER 1: Static ==="
rg --glob '**/setup.py' -n 'os\.system\|subprocess\|eval\(|exec\(' "$TARGET"
rg -n 'base64.*decode.*exec|-----BEGIN.*PRIVATE KEY|AKIA[0-9A-Z]{16}' "$TARGET"
rg -n '/bin/sh\s+-i|socket\.connect|reverse.shell' "$TARGET"

echo "=== LAYER 2: Tools ==="
clamscan -r --infected --no-summary "$TARGET"
pip-audit --requirement "$TARGET/requirements.txt" --format json 2>/dev/null
osv-scanner -r "$TARGET" --format json 2>/dev/null

echo "=== LAYER 3: Sandbox ==="
docker exec defendr-sandbox bash -c 'cd /scan && pip install --no-cache-dir -r requirements.txt 2>&1 | tail -5'

echo "=== LAYER 4: Review flagged files ==="
# Feed any findings to LLM for verdict

Error Handling

Error	Fix
rg: command not found	brew install ripgrep
clamscan: command not found	brew install clamav && freshclam
pip-audit: command not found	pip install pip-audit
osv-scanner: command not found	brew install osv-scanner
docker: command not found	Install Docker Desktop or brew install colima && colima start
freshclam fails	Check /opt/homebrew/etc/clamav/freshclam.conf has Example commented out
Container can't write	Add --tmpfs /tmp:rw,size=256m to docker run