security_scan¶

Scan code for security vulnerabilities using taint tracking to trace how untrusted data flows to dangerous operations.

Quick Reference¶

security_scan(
    file_path: str = None,           # Path to file
    code: str = None,                # Or provide code directly
    confidence_threshold: float = 0.7  # Minimum confidence
) -> SecurityResult

User Stories¶

Persona	Story	Tool Value
👤 Sarah (AI User)	"Validate AI-generated code for SQL injection before deploying"	Catch vulnerabilities early
🔰 Alex (First-Timer)	"Find security issues in code with clear explanations (CWE, remediation)"	Learn security concepts
🛡️ Marcus (Security Engineer)	"Detect SQL injection, XSS, command injection with high confidence (>0.7)"	OWASP Top 10 coverage
👥 David (Team Lead)	"Find vulnerabilities before they reach production"	Risk avoidance value
🏢 Jennifer (Enterprise Architect)	"Create audit trail of all security findings"	SOC2 evidence generation

→ See all user stories

Parameters¶

Parameter	Type	Required	Default	Description
`file_path`	string	No*	None	Absolute path to file
`code`	string	No*	None	Source code as string
`confidence_threshold`	float	No	0.7	Minimum confidence (0.0-1.0)

*One of file_path or code is required.

Response Schema¶

{
  "data": {
    "vulnerabilities": [
      {
        "type": "string",
        "severity": "string",
        "cwe": "string",
        "line": "integer",
        "column": "integer",
        "function": "string",
        "source": "string",
        "sink": "string",
        "taint_flow": [
          {
            "line": "integer",
            "code": "string",
            "taint_state": "string"
          }
        ],
        "confidence": "float",
        "remediation": "string"
      }
    ],
    "summary": {
      "critical": "integer",
      "high": "integer",
      "medium": "integer",
      "low": "integer",
      "total": "integer"
    },
    "scan_metadata": {
      "file_path": "string",
      "lines_scanned": "integer",
      "functions_analyzed": "integer"
    }
  },
  "error": null,
  "tier_applied": "string",
  "duration_ms": "integer"
}

Detected Vulnerability Types¶

Type	CWE	Severity	Description
`SQL_INJECTION`	CWE-89	Critical	Unsanitized data in SQL queries
`COMMAND_INJECTION`	CWE-78	Critical	Unsanitized data in shell commands
`XSS`	CWE-79	High	Unsanitized data in HTML output
`PATH_TRAVERSAL`	CWE-22	High	Unsanitized data in file paths
`LDAP_INJECTION`	CWE-90	High	Unsanitized data in LDAP queries
`NOSQL_INJECTION`	CWE-943	High	Unsanitized data in NoSQL queries
`SSRF`	CWE-918	High	Unsanitized URLs in requests
`HARDCODED_SECRET`	CWE-798	Medium	Passwords/keys in code

Examples¶

Basic Security Scan¶

AI PromptMCP Tool CallCLI CommandResponse

Scan api/views.py for security vulnerabilities

{
  "file_path": "/project/api/views.py"
}

codescalpel security-scan api/views.py

{
  "data": {
    "vulnerabilities": [
      {
        "type": "SQL_INJECTION",
        "severity": "CRITICAL",
        "cwe": "CWE-89",
        "line": 45,
        "column": 12,
        "function": "get_user",
        "source": "user_id (request.args.get('id'))",
        "sink": "cursor.execute(query)",
        "taint_flow": [
          {
            "line": 42,
            "code": "user_id = request.args.get('id')",
            "taint_state": "TAINTED (user input)"
          },
          {
            "line": 44,
            "code": "query = f\"SELECT * FROM users WHERE id = {user_id}\"",
            "taint_state": "TAINTED (string interpolation)"
          },
          {
            "line": 45,
            "code": "cursor.execute(query)",
            "taint_state": "SINK (SQL execution)"
          }
        ],
        "confidence": 0.95,
        "remediation": "Use parameterized queries: cursor.execute('SELECT * FROM users WHERE id = ?', (user_id,))"
      }
    ],
    "summary": {
      "critical": 1,
      "high": 0,
      "medium": 0,
      "low": 0,
      "total": 1
    },
    "scan_metadata": {
      "file_path": "/project/api/views.py",
      "lines_scanned": 150,
      "functions_analyzed": 8
    }
  },
  "tier_applied": "community",
  "duration_ms": 125
}

Scan with Lower Threshold¶

AI PromptMCP Tool CallCLI CommandResponse

Do a comprehensive security scan of handlers.py with low confidence threshold

{
  "file_path": "/project/handlers.py",
  "confidence_threshold": 0.5
}

codescalpel security-scan handlers.py --confidence-threshold 0.5

{
  "data": {
    "vulnerabilities": [
      {
        "type": "COMMAND_INJECTION",
        "severity": "CRITICAL",
        "cwe": "CWE-78",
        "line": 28,
        "function": "run_command",
        "source": "cmd (parameter)",
        "sink": "os.system(command)",
        "confidence": 0.92,
        "remediation": "Use subprocess with shell=False and argument list"
      },
      {
        "type": "PATH_TRAVERSAL",
        "severity": "HIGH",
        "cwe": "CWE-22",
        "line": 56,
        "function": "read_file",
        "source": "filename (request.form)",
        "sink": "open(filepath)",
        "confidence": 0.78,
        "remediation": "Validate path is within allowed directory using os.path.realpath"
      },
      {
        "type": "XSS",
        "severity": "HIGH",
        "cwe": "CWE-79",
        "line": 72,
        "function": "render_profile",
        "source": "username (database)",
        "sink": "render_template_string(html)",
        "confidence": 0.55,
        "remediation": "Use Jinja2 auto-escaping or markupsafe.escape()"
      }
    ],
    "summary": {
      "critical": 1,
      "high": 2,
      "medium": 0,
      "low": 0,
      "total": 3
    }
  },
  "tier_applied": "community",
  "duration_ms": 180
}

Scan Inline Code¶

AI PromptMCP Tool CallCLI CommandResponse

Check this code for vulnerabilities:

def search_users(query):
    sql = f"SELECT * FROM users WHERE name LIKE '%{query}%'"
    return db.execute(sql)

{
  "code": "def search_users(query):\n    sql = f\"SELECT * FROM users WHERE name LIKE '%{query}%'\"\n    return db.execute(sql)"
}

# Save code to temp file first
cat > temp_scan.py << 'EOF'
def search_users(query):
    sql = f"SELECT * FROM users WHERE name LIKE '%{query}%'"
    return db.execute(sql)
EOF

codescalpel security-scan temp_scan.py

{
  "data": {
    "vulnerabilities": [
      {
        "type": "SQL_INJECTION",
        "severity": "CRITICAL",
        "cwe": "CWE-89",
        "line": 2,
        "function": "search_users",
        "source": "query (parameter)",
        "sink": "db.execute(sql)",
        "taint_flow": [
          {"line": 1, "code": "def search_users(query):", "taint_state": "TAINTED (parameter)"},
          {"line": 2, "code": "sql = f\"SELECT...{query}...\"", "taint_state": "TAINTED (f-string)"},
          {"line": 3, "code": "return db.execute(sql)", "taint_state": "SINK"}
        ],
        "confidence": 0.98,
        "remediation": "Use parameterized query: db.execute('SELECT * FROM users WHERE name LIKE ?', ('%' + query + '%',))"
      }
    ],
    "summary": {"critical": 1, "high": 0, "medium": 0, "low": 0, "total": 1}
  },
  "tier_applied": "community",
  "duration_ms": 35
}

Hardcoded Secret Detection¶

AI PromptMCP Tool CallCLI CommandResponse

Check config.py for hardcoded secrets

{
  "file_path": "/project/config.py",
  "confidence_threshold": 0.6
}

codescalpel security-scan config.py --confidence-threshold 0.6

{
  "data": {
    "vulnerabilities": [
      {
        "type": "HARDCODED_SECRET",
        "severity": "MEDIUM",
        "cwe": "CWE-798",
        "line": 15,
        "code": "API_KEY = \"sk-1234567890abcdef\"",
        "secret_type": "api_key",
        "confidence": 0.88,
        "remediation": "Use environment variables: API_KEY = os.environ.get('API_KEY')"
      },
      {
        "type": "HARDCODED_SECRET",
        "severity": "MEDIUM",
        "cwe": "CWE-798",
        "line": 18,
        "code": "DATABASE_PASSWORD = \"super_secret_password\"",
        "secret_type": "password",
        "confidence": 0.92,
        "remediation": "Use environment variables or secrets manager"
      }
    ],
    "summary": {"critical": 0, "high": 0, "medium": 2, "low": 0, "total": 2}
  },
  "tier_applied": "community",
  "duration_ms": 45
}

Tier Differences¶

This tool is available at all tiers. What differs are the limits and capabilities:

Feature	Community	Pro	Enterprise
Availability	✅ Available	✅ Available	✅ Available
Basic taint analysis	✅	✅	✅
Max paths	10	100	Unlimited
All vulnerability types	✅ SQL, XSS, etc.	✅ SQL, XSS, etc.	✅ SQL, XSS, etc.
Taint flow visualization	✅	✅	✅
Custom sinks	Not available	✅	✅
Custom sanitizers	Not available	✅	✅
SARIF export	Not available	✅	✅
Compliance reporting	Not available	Not available	✅ OWASP/CWE

Understanding Confidence Scores¶

Score	Meaning	Action
0.9-1.0	Very likely vulnerability	Fix immediately
0.7-0.9	Probable vulnerability	Review and fix
0.5-0.7	Possible vulnerability	Investigate
<0.5	Unlikely	Low priority

Factors affecting confidence:

Direct data flow: Higher confidence
Multiple transformations: Lower confidence
Sanitizer presence: Lower confidence
Unknown functions: Lower confidence

Tier Limits¶

Security scanning capabilities vary by tier:

Feature	Community	Pro	Enterprise
Max findings	50	Unlimited	Unlimited
Max file size	500 KB	Unlimited	Unlimited
Vulnerability types	OWASP Top 10	All	All
Custom sanitizers	❌	✅	✅
SARIF export	❌	✅	✅
Compliance reporting	❌	❌	✅ OWASP/CWE

Community Tier¶

✅ OWASP Top 10 vulnerability detection
✅ SQL injection, XSS, command injection, path traversal
✅ NoSQL injection, LDAP injection
✅ CWE mappings and remediation guidance
⚠️ Max 50 findings per scan
⚠️ Max 500 KB file size

Pro Tier¶

✅ All Community features
✅ Unlimited findings and file size
✅ Extended vulnerability types (deserialization, XXE, SSRF)
✅ Custom sanitizer patterns
✅ SARIF export for CI/CD integration
✅ Advanced taint flow analysis

Enterprise Tier¶

✅ All Pro features
✅ Compliance reporting (OWASP, CWE, SANS Top 25)
✅ PDF audit reports
✅ Organization-wide policy enforcement
✅ Audit trail and evidence generation
✅ Multi-framework support (Django, Flask, Express, Spring)

Key Difference: Coverage - Community: OWASP Top 10 (10 vulnerability classes) - Pro: Extended coverage (20+ vulnerability classes) - Enterprise: Comprehensive + compliance (30+ classes, regulatory frameworks)

→ See OWASP Top 10 coverage

Best Practices¶

Start with default threshold - 0.7 balances coverage and precision
Lower threshold for audits - Use 0.5 for comprehensive review
Check taint flows - Understand how data reaches sinks
Follow remediation advice - Tool-specific fixes provided
Use cross-file scan for full coverage - Single file misses cross-module flows

cross_file_security_scan - Multi-file analysis
scan_dependencies - Dependency CVEs
unified_sink_detect - Polyglot detection

security_scan¶

Quick Reference¶

User Stories¶

Parameters¶

Response Schema¶

Detected Vulnerability Types¶

Examples¶

Basic Security Scan¶

Scan with Lower Threshold¶

Scan Inline Code¶

Hardcoded Secret Detection¶

Tier Differences¶

Understanding Confidence Scores¶

Tier Limits¶

Community Tier¶

Pro Tier¶

Enterprise Tier¶

Best Practices¶

Related Tools¶