Documentation - Mikmbr Security Scanner

🚀 Quick Start

Get started with Mikmbr in under 2 minutes:

# Install
pip install mikmbr

# Scan your code
mikmbr scan .

# See results with context
mikmbr scan . --context 3

📦 Installation

Via pip (Recommended)

pip install mikmbr

From Source

git clone https://github.com/tonybowen-me/Mikmbr
cd Mikmbr
pip install -e .

Requirements

Python 3.9 or higher
pyyaml >= 6.0

💻 Basic Usage

Scan a File

mikmbr scan myfile.py

Scan a Directory

mikmbr scan /path/to/project

Scan Current Directory

mikmbr scan .

Output Formats

# Human-readable (default)
mikmbr scan . --format human

# JSON format
mikmbr scan . --format json

# SARIF (for GitHub Code Scanning)
mikmbr scan . --format sarif

✨ Features (v1.8)

📦 Dependency Scanning (NEW)

Detect vulnerabilities in third-party packages with --check-deps

mikmbr scan . --check-deps

🎯 Dependencies-Only Mode (NEW)

Skip code analysis and scan only dependencies

mikmbr scan . --deps-only

🚦 Exit Code Control

Control when CI/CD builds fail with --fail-on

mikmbr scan . --fail-on high

📄 Code Context

See surrounding code with --context

mikmbr scan . --context 3

🔕 Inline Suppression

Mark false positives

# mikmbr: ignore[SQL_INJECTION]
query = build_query()

🎯 Framework Rules

Django, Flask, FastAPI specific checks

Dependency Scanning

Scan your project dependencies for known vulnerabilities using the OSV (Open Source Vulnerabilities) database:

# Scan code + dependencies
mikmbr scan . --check-deps

# Scan only dependencies (fast)
mikmbr scan . --deps-only

# Combine with other flags
mikmbr scan . --check-deps --fail-on high --format json

Supported dependency files:

requirements.txt - Standard pip format
pyproject.toml - PEP 621 and Poetry format

Example output:

[HIGH] requirements.txt:3
  Rule: VULN_DEPENDENCY
  CWE: CWE-89
  Package django version 2.2.0 has known vulnerability CVE-2023-12345: SQL injection in admin panel
  Remediation: Upgrade django to >= 2.2.28
  References:
    - https://osv.dev/vulnerability/PYSEC-2023-12345

Exit Code Configuration

Control when builds fail based on severity:

Flag	Fails On	Use Case
`--fail-on critical`	CRITICAL only	Legacy codebases
`--fail-on high`	CRITICAL HIGH	Pull requests
`--fail-on medium`	CRITICAL HIGH MEDIUM	Main branch
`--fail-on low`	All severities	Strict enforcement

Code Context Lines

Show surrounding code for better understanding:

mikmbr scan app.py --context 3

Output example:

[HIGH] app.py:42
  Rule: SQL_INJECTION
  Code:
     40 |     conn = sqlite3.connect('db.sqlite')
     41 |     cursor = conn.cursor()
  >  42 |     query = f"SELECT * FROM users WHERE id = {user_id}"
     43 |     cursor.execute(query)
     44 |     return cursor.fetchone()

🔄 CI/CD Integration

GitHub Actions

name: Security Scan
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'

      - name: Install Mikmbr
        run: pip install mikmbr

      - name: Run Security Scan
        run: mikmbr scan . --check-deps --fail-on high --format json

With Dependency Scanning Only (Fast)

      - name: Check Dependencies
        run: mikmbr scan . --deps-only --fail-on high

GitHub Code Scanning (SARIF)

- name: Security Scan
  run: mikmbr scan . --format sarif > results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: results.sarif

GitLab CI

security_scan:
  image: python:3.9
  script:
    - pip install mikmbr
    - mikmbr scan . --fail-on high --format json
  allow_failure: false

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: mikmbr
        name: Mikmbr Security Scan
        entry: mikmbr scan --context 2 --fail-on high
        language: system
        pass_filenames: false

⚙️ Configuration

Configuration File

Create .mikmbr.yaml in your project root:

exclude:
  - "tests/"
  - "venv/"
  - "*.min.js"

rules:
  SQL_INJECTION:
    enabled: true
    severity: HIGH

  HARDCODED_SECRET:
    enabled: true
    severity: HIGH

output:
  format: human
  verbose: false

Command Line Options

Option	Description	Example
`--format`	Output format (human, json, sarif)	`--format json`
`--verbose`	Show detailed information	`--verbose`
`--fail-on`	Exit code threshold	`--fail-on high`
`--context`	Show N lines around findings	`--context 3`
`--config`	Path to config file	`--config .mikmbr.yaml`

🔍 Detection Rules (25+)

Core Security Rules (21)

Rule	Severity	Description
TEMPLATE_INJECTION	CRITICAL	Server-Side Template Injection (SSTI)
SQL_INJECTION	HIGH	SQL injection vulnerabilities
COMMAND_INJECTION	HIGH	OS command injection
DANGEROUS_EXEC	HIGH	Use of eval(), exec(), compile()
HARDCODED_SECRET	HIGH	Hardcoded passwords, API keys, tokens
SSRF	HIGH	Server-Side Request Forgery
PATH_TRAVERSAL	HIGH	Directory traversal attacks
WEAK_CRYPTO	MEDIUM	Weak cryptographic algorithms (MD5, SHA1)
INSECURE_DESERIALIZATION	HIGH	Unsafe pickle, yaml.load()
XSS	HIGH	Cross-Site Scripting

Framework-Specific Rules

Django (6 rules)

Raw SQL queries
mark_safe() usage
DEBUG=True in production
Hardcoded SECRET_KEY
Extra() SQL injection
Safe string bypass

Flask (6 rules)

send_file() path traversal
render_template_string() SSTI
Debug mode enabled
Insecure cookie settings
Session configuration
CORS misconfiguration

FastAPI (5 rules)

Missing input validation
Path traversal in file endpoints
CORS allow all origins
Dangerous dependencies
Insecure JWT configuration

📝 Examples

Example 1: Local Development

# See all issues with context
mikmbr scan . --context 3 --verbose

Example 2: Pull Request Check

# Fail on HIGH+ issues, show context
mikmbr scan . --fail-on high --context 2

Example 3: Gradual Adoption

# Week 1: Only block CRITICAL
mikmbr scan . --fail-on critical

# Month 2: Tighten to HIGH
mikmbr scan . --fail-on high

# Month 6: Full enforcement
mikmbr scan . --fail-on medium

Example 4: Suppressing False Positives

# Suppress specific rule
# mikmbr: ignore[SQL_INJECTION]
query = build_safe_query(user_input)

# Suppress multiple rules
# mikmbr: ignore[SQL_INJECTION, COMMAND_INJECTION]
execute_query(sanitized_input)

Example 5: JSON Output for Automation

mikmbr scan . --format json > results.json

# Process with jq
mikmbr scan . --format json | jq '.findings[] | select(.severity == "HIGH")'

🔧 Troubleshooting

Common Issues

⚠️ "No module named 'mikmbr'"

Solution: Ensure mikmbr is installed: pip install mikmbr

⚠️ "SyntaxError: invalid syntax"

Solution: Mikmbr requires Python 3.9+. Check version: python --version

⚠️ Too many false positives

Solution: Use inline suppression or adjust config:

# Suppress in code
# mikmbr: ignore[RULE_ID]

# Or disable in config
rules:
  RULE_ID:
    enabled: false

Performance Tips

Exclude virtual environments and dependencies: exclude: ["venv/", "node_modules/"]
Use --context 0 for faster CI/CD
Scan specific directories instead of entire project

Getting Help

📖 Check the GitHub README
🐛 Report issues on GitHub Issues
💬 Ask questions in Discussions

🧪 Testing Mikmbr

Quick Test

Create a test file to verify Mikmbr is working:

# test_security.py
import sqlite3

# This should trigger SQL_INJECTION
def get_user(user_id):
    conn = sqlite3.connect('db.sqlite')
    cursor = conn.cursor()
    query = f"SELECT * FROM users WHERE id = {user_id}"
    cursor.execute(query)
    return cursor.fetchone()

Run scan:

mikmbr scan test_security.py --context 2

Expected output:

[HIGH] test_security.py:8
  Rule: SQL_INJECTION
  Issue: SQL query built with string concatenation
  Fix: Use parameterized queries
  Code:
       6 |     conn = sqlite3.connect('db.sqlite')
       7 |     cursor = conn.cursor()
  >    8 |     query = f"SELECT * FROM users WHERE id = {user_id}"
       9 |     cursor.execute(query)
      10 |     return cursor.fetchone()

📦 Version Information

Current Version: 1.7.0

Release Date: January 2026

What's New in v1.7

🚦 Exit code configuration (--fail-on)
📄 Code context lines (--context)
⚡ CRITICAL severity level
🔧 SARIF v2.1 with CRITICAL support

View Full Changelog →

📚 Quick Navigation