Building an AI-Agent Based Python Security Scanner.

The Problem 

Manual security scanning of Python dependencies is time-consuming and error prone. Developers often skip vulnerability checks during development, leading to security debt that compounds over time. Existing tools either lack intelligence or require complex setup and maintenance. 

I needed a solution that could automatically scan Python packages, identify vulnerabilities, and provide actionable recommendations without requiring extensive security expertise. Or at most allow vibe coders to scan all the packages in their code with minimal set up.

The Solution: AI Agent-based scanner 

An AI agent-based security scanner that uses intelligent agents to analyze Python dependencies and identify vulnerabilities. It combines multiple data sources with AI reasoning to provide comprehensive security analysis. 

Architecture Overview 

Technical Implementation 

Core Components: 

1. Dependency Parser: Handles both requirements.txt and environment.yml files 
2. AI Agent: Uses Hugging Face models via smolagents framework 
3. Multi-Tool Integration: Custom tools for PyPI , GitHub , and vulnerability scanning 
4. Structured Output: Consistent reporting across different output formats 

Key Technologies: 

• Python 3.11+ 
• Hugging Face smolagents framework 
• PyPI API 
• GitHub API 
• OSV (Open-Source Vulnerabilities) database 

Implementation Challenges 

Challenge 1: Inconsistent AI Output 

The AI agent produced different output structures across runs: 

python 

# Sometimes: 
{'vulnerable_packages': {'pkg': [...]}} 
 
# Other times: 
{'executive_summary': {'vulnerable_packages': {'pkg': [...]}}}        

For anyone interested in understanding more about AI Agents, I would recommend the agents-course (Hugging Face Agents Course).

Solution: Use Agent Tools

Implemented a robust FinalAnswerTool with structured validation. 

python 

class FinalAnswerTool(Tool): 
    def forward(self, answer: Any) -> Dict[str, Any]: 
        if isinstance(answer, dict): 
            standardized = { 
                "vulnerable_packages": {}, 
                "upgrade_recommendations": {}, 
                "overall_risk_assessment": "No assessment provided" 
            } 
             
            # Handle multiple possible structures 
            if "vulnerable_packages" in answer: 
                standardized["vulnerable_packages"] = answer["vulnerable_packages"] 
            elif "executive_summary" in answer and isinstance(answer["executive_summary"], dict): 
                if "vulnerable_packages" in answer["executive_summary"]: 
                    standardized["vulnerable_packages"] = answer["executive_summary"]["vulnerable_packages"] 
             
            return standardized         

Challenge 2: Multi-Source Data Integration 

Different APIs return vulnerability data in incompatible formats. 

Solution: Use a Parser.

Created unified data models and source-specific parsers that normalize data into a consistent structure.

Usage Example 

bash 

# Install dependencies 
pip install motionstream 
 
# Scan requirements file 
motionstream scan requirements.txt 
 
# Generate JSON report 
motionstream scan requirements.txt --output json 
 
# Generate HTML report 
motionstream scan environment.yml --output html        

Sample Output 

🔒 MotionStream Security Report 
 
📦 Scanned 3 packages: 
   ✓ requests 2.32.4 
   ✓ pandas None 
   ❌ browser-use 0.1.44 - HIGH vulnerabilities found 
 
🔍 Security Issues Found: 
 
⚠ HIGH: browser-use 0.1.44 has file access vulnerabilities 
  Impact: package 
  Fix: pip install browser-use>=0.2.6 
 
📊 Summary: 1 vulnerabilities found (0 Critical, 1 High) 
🎯 Recommendation: Update vulnerable packages immediately         

Results and Impact 

• Accuracy: Successfully identified all known vulnerabilities in test cases.
• Performance: Average scan time of 15-30 seconds for typical Python projects.
• Usability: Color-coded terminal output with clear remediation steps.
• Flexibility: Multiple output formats for different use cases 

Lessons Learned 

1. AI Output Consistency: Always validate and structure AI agent outputs 
2. Error Handling: Robust fallback mechanisms are essential when dealing with external APIs 
3. User Experience: Clear, actionable output is more valuable than comprehensive technical details 
4. Modular Design: Separating tools, parsers, and formatters enables easier testing and maintenance 

Future Enhancements 

Immediate Next Steps: 

• CI/CD pipeline integration (GitHub Actions, GitLab CI)
• Support for additional package managers (npm, Maven, Composer)
• Vulnerability trend analysis and risk scoring
• Code-based API and configuration scanning

Long-term Vision: 

• Machine learning models for false positive reduction 
• Integration with security information and event management (SIEM) systems 
• Automated pull request generation for vulnerability fixes 

Technical Specifications 

System Requirements: 

• Python 3.11 or higher 
• Hugging Face Token (free tier sufficient) 
• Internet connection for API access 

Performance Metrics: 

• Memory usage: ~200MB baseline 
• Network requests: 2-5 per package 
• Processing time: 5-10 seconds per package 

Conclusion 

This demonstrates how AI agents can effectively automate security scanning while maintaining accuracy and usability. The key success factors were handling AI output inconsistency, robust error handling, and focusing on developer experience. 

The project proves that combining multiple data sources with AI reasoning can produce more intelligent security analysis than traditional rule-based approaches. Source code and documentation available on GitHub: https://github.com/callezenwaka/motionstream.