> ## Documentation Index
> Fetch the complete documentation index at: https://acm-aa28ebf6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Security Pipeline

> 5-step automated security scanning for MCP servers

## Overview

SuperBox implements a comprehensive **5-step security pipeline** that automatically scans every MCP server before publication to ensure security, quality, and reliability.

<Frame>
  <div className="rounded-lg bg-gradient-to-r from-red-500 via-orange-500 to-green-500 p-6 text-white">
    <h3 className="mb-4 text-2xl font-bold">Zero-Trust Security Model</h3>

    <p>
      Every MCP server undergoes rigorous automated security scanning before
      deployment.
    </p>
  </div>
</Frame>

<CardGroup cols={3}>
  <Card title="SonarCloud" icon="magnifying-glass-chart" color="#4E9BCD">
    Code quality & security analysis
  </Card>

  <Card title="Tool Discovery" icon="magnifying-glass" color="#10B981">
    Validates MCP tools exist in source code
  </Card>

  <Card title="Snyk" icon="shield-virus" color="#7856FF">
    Dependency vulnerability scanning
  </Card>

  <Card title="GitGuardian" icon="key" color="#FF6B6B">
    Secrets and credentials scanning
  </Card>

  <Card title="Bandit" icon="python" color="#FFD43B">
    Python security vulnerability detection
  </Card>
</CardGroup>

## Security Pipeline Architecture

```mermaid theme={null}
graph TD
 A[Developer pushes code] --> B[superbox push]
 B --> C{Step 1: SonarCloud}
 C -->|Pass| D{Step 2: Tool Discovery}
 C -->|Fail| Z[Reject with report]

 D -->|Pass| E{Step 3: Snyk}
 D -->|Fail| Z

 E -->|Pass| F{Step 4: GitGuardian}
 E -->|Fail| Z

 F -->|Pass| G{Step 5: Bandit}
 F -->|Critical| Z
 F -->|Warning| G

 G -->|Pass| H[Upload to R2 Registry]
 G -->|Fail| Z

 H --> I[Publish to Marketplace]

 Z --> K[Developer fixes issues]
 K --> B
```

## Pipeline Steps

### Step 1: SonarCloud Analysis

<Tabs>
  <Tab title="Overview">
    **SonarCloud** performs comprehensive code quality and security analysis:

    <AccordionGroup>
      <Accordion title="Code Smells" icon="nose">
        Identifies maintainability issues:

        * Complex functions
        * Duplicated code
        * Long parameter lists
        * Cognitive complexity
      </Accordion>

      <Accordion title="Bugs" icon="bug">
        Detects potential runtime errors:

        * Null pointer dereferences
        * Resource leaks
        * Logic errors
        * Exception handling issues
      </Accordion>

      <Accordion title="Security Hotspots" icon="fire">
        Highlights security-sensitive code:

        * SQL injection risks
        * XSS vulnerabilities
        * Insecure crypto usage
        * Authentication bypasses
      </Accordion>

      <Accordion title="Code Coverage" icon="chart-line">
        Measures test coverage:

        * Line coverage
        * Branch coverage
        * Function coverage
        * Target: >80% coverage
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Configuration">
    ```properties sonar-project.properties theme={null}
    sonar.projectKey=superbox-mcp-server
    sonar.projectName=Weather MCP Server
    sonar.projectVersion=1.0.0

    # Source code location

    sonar.sources=src
    sonar.tests=tests

    # Language

    sonar.language=py
    sonar.python.version=3.11

    # Coverage

    sonar.python.coverage.reportPaths=coverage.xml

    # Quality gates

    sonar.qualitygate.wait=true
    sonar.qualitygate.timeout=300

    # Rules

    sonar.python.pylint.reportPath=pylint-report.txt
    sonar.python.xunit.reportPath=xunit-report.xml

    ```
  </Tab>

  <Tab title="Execution">
    ```bash theme={null}
    # Run SonarCloud scanner
    sonar-scanner \
      -Dsonar.host.url=https://sonarcloud.io \
      -Dsonar.login=$SONAR_TOKEN \
      -Dsonar.projectKey=$PROJECT_KEY

    # Wait for quality gate
    quality_gate=$(curl -s \
      -u $SONAR_TOKEN: \
      "https://sonarcloud.io/api/qualitygates/project_status?projectKey=$PROJECT_KEY" \
      | jq -r '.projectStatus.status')

    if [ "$quality_gate" != "OK" ]; then
      echo "Quality gate failed"
      exit 1
    fi
    ```
  </Tab>

  <Tab title="Results">
    Example SonarCloud report:

    ```json theme={null}
    {
    "projectStatus": {
     "status": "OK",
     "conditions": [
    {
    "status": "OK",
    "metricKey": "coverage",
    "comparator": "LT",
    "errorThreshold": "80",
    "actualValue": "85.3"
    },
    {
    "status": "OK",
    "metricKey": "security_rating",
    "actualValue": "1.0"
    },
    {
    "status": "OK",
    "metricKey": "reliability_rating",
    "actualValue": "1.0"
    }
     ],
     "periods": [],
     "ignoredConditions": false
    }
    }
    ```

    <Check>**Security Rating: A** - No security vulnerabilities</Check>
    <Check>**Reliability Rating: A** - No bugs detected</Check>
    <Check>**Coverage: 85.3%** - Exceeds 80% threshold</Check>
  </Tab>
</Tabs>

### Step 2: Tool Discovery

The repository is cloned to a temp directory. Source files are scanned with regex to find all MCP tool definitions - functions decorated with `@*.tool()`.

<Info>
  If no tool definitions are found, `superbox push` fails with a list of expected function names.
</Info>

### Step 3: Snyk Dependency Scan

**Snyk** scans `requirements.txt` for known CVEs in Python dependencies.

<CardGroup cols={2}>
  <Card title="CVE Detection" icon="shield-virus">
    Checks against Snyk's vulnerability database
  </Card>

  <Card title="Severity Levels" icon="exclamation">
    Critical, High, Medium, Low
  </Card>
</CardGroup>

The scan fails the pipeline on any critical or high severity findings.

### Step 4: GitGuardian Secrets Detection

<Tabs>
  <Tab title="Overview">
    **GitGuardian** scans for exposed secrets and credentials:

    <CardGroup cols={2}>
      <Card title="350+ Detectors" icon="key">
        API keys, tokens, passwords
      </Card>

      <Card title="High Accuracy" icon="bullseye">
        Low false positive rate
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Detected Secrets">
    Common secrets detected:

    * Cloud provider access keys
    * GitHub tokens (ghp\_...)
    * OpenAI API keys (sk-...)
    * Database URLs (postgres\://user:pass\@...)
    * Private keys (-----BEGIN RSA PRIVATE KEY-----)
    * JWT tokens
    * Stripe API keys (sk\_live\_...)
  </Tab>

  <Tab title="Results">
    Example output when a secret is found:

    ```json theme={null}
    {
    "secrets_found": [
     {
    "type": "AWS Access Key",
    "file": "config.py",
    "line": 23,
    "match": "AKIAIOSFODNN7EXAMPLE",
    "severity": "critical"
     }
    ],
    "total_secrets": 1
    }
    ```

    <Warning>**Critical:** Exposed credential found in source code. Remove secrets before pushing.</Warning>
  </Tab>
</Tabs>

### Step 5: Bandit Security Audit

<Tabs>
  <Tab title="Overview">
    **Bandit** scans Python code for common security issues:

    <CardGroup cols={2}>
      <Card title="50+ checks" icon="shield">
        B201-B506 security rules for Python
      </Card>

      <Card title="Severity Levels" icon="exclamation">
        Low, Medium, High
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Common Issues">
    <AccordionGroup>
      <Accordion title="B108: Hardcoded Temporary File" icon="file">
        ```python theme={null}
        # Bad
        with open('/tmp/secrets.txt', 'w') as f:
        f.write(api_key)

        # Good
        import tempfile
        with tempfile.NamedTemporaryFile(delete=False) as f:
        f.write(api_key.encode())
        ```
      </Accordion>

      <Accordion title="B201: Flask Debug Mode" icon="bug">
        ```python theme={null}
        # Bad
        app.run(debug=True)

        # Good
        app.run(debug=False)
        ```
      </Accordion>

      <Accordion title="B608: SQL Injection" icon="database">
        ```python theme={null}
        # Bad
        query = f"SELECT * FROM users WHERE id = {user_id}"

        # Good
        query = "SELECT * FROM users WHERE id = %s"
        cursor.execute(query, (user_id,))
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

## Security Scoring

Each scan contributes to an overall security score:

<Tabs>
  <Tab title="Score Calculation">
    ```python theme={null}
    def calculate_security_score(scan_results):
     score = 100

     # SonarCloud penalties
     score -= scan_results['sonarcloud']['bugs'] * 5
     score -= scan_results['sonarcloud']['vulnerabilities'] * 10

     # Snyk penalties
     score -= scan_results['snyk']['critical'] * 20
     score -= scan_results['snyk']['high'] * 10

     # GitGuardian penalties
     score -= scan_results['gitguardian']['secrets'] * 50

     # Bandit penalties
     score -= scan_results['bandit']['high'] * 15
     score -= scan_results['bandit']['medium'] * 5

     return max(0, min(100, score))
    ```
  </Tab>

  <Tab title="Score Grades">
    | Score  | Grade | Status                    |
    | ------ | ----- | ------------------------- |
    | 95-100 | A+    | Excellent - Auto-approved |
    | 85-94  | A     | Good - Auto-approved      |
    | 75-84  | B     | Fair - Manual review      |
    | 65-74  | C     | Needs improvement         |
    | 0-64   | F     | Rejected - Fix issues     |
  </Tab>

  <Tab title="Example Report">
    ```json theme={null}
    {
    "server_id": "weather-mcp-123",
    "scan_timestamp": "2024-01-15T10:30:00Z",
    "overall_score": 92,
    "grade": "A",
    "status": "approved",
    "scans": {
     "SonarCloud": {
    "status": "passed",
    "bugs": 0,
    "vulnerabilities": 0,
    "code_smells": 3,
    "coverage": 87.5
     },
     "bandit": {
    "status": "passed",
    "high": 0,
    "medium": 1,
    "low": 2
     },
     "gitguardian": {
    "status": "passed",
    "secrets": 0
     },
     "snyk": {
    "status": "passed",
    "critical": 0,
    "high": 0
     },
     "tool_discovery": {
    "status": "passed",
    "tools_found": 3
     }
    }
    }
    ```
  </Tab>
</Tabs>

## Best Practices

<Check>**Never hardcode secrets** - Use environment variables</Check>
<Check>**Keep dependencies updated** - Regular security patches</Check>
<Check>**Use parameterized queries** - Prevent SQL injection</Check>
<Check>**Validate all inputs** - Sanitize user data</Check>
<Check>**Implement rate limiting** - Prevent abuse</Check>
<Check>**Log security events** - Audit trail</Check>

## Next Steps

<CardGroup cols={2}>
  <Card title="MCP Servers" icon="server" href="/concepts/mcp-servers">
    Learn about MCP protocol
  </Card>

  <Card title="Sandboxes" icon="box" href="/concepts/sandboxes">
    Cloudflare Durable Object sandboxes
  </Card>

  <Card title="CLI Push Command" icon="terminal" href="/cli/push">
    Publish with security scanning
  </Card>

  <Card title="API Documentation" icon="book" href="/api/introduction">
    Explore API endpoints
  </Card>
</CardGroup>