CodeSentinel is a single-file, production-ready secure Python code analyzer and sandbox executor designed to safely inspect and execute untrusted or AI-generated Python code without risking system integrity.
It performs static AST analysis, assigns a risk score, applies heuristic AI probability checks, and runs code inside a time-limited, restricted sandbox before allowing optional full-access execution.
Platform Compatibility
| Platform | Supported | Notes |
|---|---|---|
| Windows | ✅ Yes | freeze_support enabled |
| Linux | ✅ Yes | Fully supported |
| macOS | ✅ Yes | Fully supported |
| WSL | Depends on config |
Feature Comparison
| Capability | Supported | Notes |
|---|---|---|
| AST-based static analysis | ✅ | No code execution required |
| Dangerous import detection | ✅ | os, subprocess, socket, etc. |
| Unsafe built-in detection | ✅ | eval, exec, compile, open |
| Attribute call detection | ✅ | os.system, os.remove, etc. |
| Risk scoring (0–10) | ✅ | Severity-weighted |
| AI heuristic probability | ✅ | Offline, no APIs |
| Restricted sandbox execution | ✅ | Isolated process |
| Execution timeout | ✅ | Prevents infinite loops |
| Full-access execution | Requires manual confirmation | |
| Internet access | ❌ | Fully offline by design |
AI Heuristic Signals
| Signal | Description | Weight |
|---|---|---|
| Long lines | >120 characters | Medium |
| Dense logic | High complexity | Medium |
| Repetitive patterns | Copy-like structure | Low |
| Obfuscation | Unusual formatting | High |
Security Layer Breakdown
| Layer | Protection Applied | Purpose |
|---|---|---|
| Static Analysis | AST inspection | Detect risky code early |
| Runtime Isolation | Separate process | Prevent host contamination |
| Built-ins | Whitelisted only | Block file/system access |
| Imports | Policy-based blocking | Disable dangerous modules |
| Timeout | Forced termination | Stop infinite or hanging code |
| Unsafe Mode | Manual consent | Prevent accidental harm |
Built ins Availability Table
| Built-in | Restricted Mode | Unsafe Mode |
|---|---|---|
| ✅ Allowed | ✅ Allowed | |
| input | ✅ Allowed | ✅ Allowed |
| open | ❌ Blocked | ✅ Allowed |
| exec | ❌ Blocked | ✅ Allowed |
| eval | ❌ Blocked | ✅ Allowed |
| import | 🔒 Restricted | ✅ Full |
Risk Severity mapping
| Severity Score | Level | Meaning |
|---|---|---|
| 0–2 | 🟢 LOW | Minimal or no risk |
| 3–4 | 🟡 MEDIUM | Potentially unsafe |
| 5–7 | 🟠 HIGH | Dangerous patterns detected |
| 8–10 | 🔴 CRITICAL | Immediate system risk |
Detected Issue Types
| Issue Type | Example | Severity |
|---|---|---|
| Dangerous module | import os | 🔴 High |
| Unsafe built-in | eval("code") | 🔴 High |
| System call | os.system("cmd") | 🔴 Critical |
| File deletion | os.remove("x") | 🔴 Critical |
| Long lines | >120 chars | 🟡 Medium |
Execution Outcome Matrix.
| Scenario | Restricted Mode Result | Unsafe Mode Result |
|---|---|---|
| Safe code | ✅ Executes normally | ✅ Executes normally |
| File deletion attempt | ❌ Blocked | |
| Dangerous import | ❌ Blocked | |
| Infinite loop | ❌ Terminated | ❌ May hang system |
| Network access | ❌ Blocked |
CLI Command Reference
| Command | Description | Executes Code |
|---|---|---|
| scan <file.py> | Analyze code only | ❌ No |
| run <file.py> | Run in restricted sandbox | ✅ Yes (safe) |
| Unsafe override | Full access execution |
Sandbox mode Comparison
| Feature | Restricted Mode | Unsafe Mode |
|---|---|---|
| Filesystem access | ❌ Blocked | ✅ Allowed |
| Dangerous imports | ❌ Blocked | ✅ Allowed |
| Built-ins | Whitelisted | Full Python |
| Timeout enforced | ✅ Yes | ❌ No |
| User confirmation | ❌ No | ✅ Required |
| System risk | 🟢 Low | 🔴 High |
Ideal user profiles.
| User | How CodeSentinel Helps |
|---|---|
| AI Developers | Inspect AI-generated scripts |
| Security Researchers | Test unsafe code safely |
| Students | Learn Python security |
| Educators | Demonstrate sandboxing |
| Offline Users | Secure execution without internet |
Roadmap Status
| Feature | Status |
|---|---|
| Core analyzer | ✅ Complete |
| Restricted sandbox | ✅ Complete |
| Risk scoring | ✅ Complete |
| JSON report export | ⏳ Planned |
| Custom policies | ⏳ Planned |
| GUI interface | ⏳ Planned |
| PyPI package | ⏳ Planned |
Community Engagement
| Action | Impact |
|---|---|
| ⭐ Star the repo | Helps visibility |
| 🐛 Report issues | Improves security |
| 🔧 Submit PRs | Grows the project |
| 📢 Share | Helps safe coding |
🔍 Static Security Analysis
AST-based inspection (no execution required)
Detects:
1)Dangerous module imports (os, subprocess, socket, etc.) 2)Unsafe built-ins (eval, exec, compile, open) 3)High-risk attribute calls (os.system, os.remove, etc.) 4)Line-accurate reporting with code snippets
🧮 Risk Scoring System
1)Severity-weighted scoring model 2)Normalized 0–10 risk score 3.Automatically flags high-risk files
🤖 AI Heuristic Probability
1)Lightweight heuristic to estimate AI-generated code likelihood 2)Zero external APIs 3)Fully offline and deterministic
🧪 Secure Sandbox Execution
1)Runs code in a separate process 2)Enforced execution timeout 3)Restricted built-ins and blocked filesystem access 4)Dangerous imports disabled at runtime 5)Optional manual override for unrestricted execution
🪟 Windows-Safe by Design
1)Uses multiprocessing.freeze_support() 2)Compatible with Windows executables and frozen builds
No dependencies required.
git clone https://github.com/LegedsDaD/codesentinel.git cd codesentinel
Python 3.8+ is required.
python codesentinel.py scan example.py
Output includes:
Detected issues Severity levels Line numbers and code snippets Risk score AI probability estimate
python codesentinel.py run example.py
By default:
Filesystem access is blocked Dangerous modules are disabled Execution is time-limited
🚨 Run with full system access (dangerous)
If high-risk issues are detected, CodeSentinel requires explicit confirmation:
Type EXACTLY 'I UNDERSTAND' to run UNSAFE mode:
This prevents accidental execution of malicious code.
📊 Example Output [HIGH] Line 12: Import of dangerous module 'os'
import os
[HIGH] Line 25: Dangerous call 'os.remove()'
os.remove("important.txt")
🧮 Risk Score: 3/10 🤖 AI-generated probability: 0%
Layer Protection Static Analysis AST inspection Runtime Sandbox Isolated process Built-ins Whitelisted only Imports Blocked by policy Timeout Forced termination Unsafe Mode Manual confirmation
No Python sandbox is perfectly secure. CodeSentinel is designed for risk reduction, not absolute isolation.
1)Reviewing AI-generated Python code 2)Executing code from untrusted sources 3)Teaching Python security concepts 4)Secure local code testing 5)Building higher-level AI agents or coding tools
MIT License You are free to use, modify, and distribute this software.
1.JSON / SARIF report export 2.Custom security policies 3.Memory & CPU usage limits 4.Plugin-based analyzers 5.GUI and editor integrations
If you find CodeSentinel useful don't forget to leave a star behind. Thank You
LegedsDaD Independent Developer