layerd/hex

By layerd

•Updated 5 months ago

Mission-critical AI/ML model security scanner - detect vulnerabilities, malware & compliance issues

Image

Security

7.0K

Overview Tags

layerd/hex repository overview

⁠Hex - AI Model Security Scanner by Layerd AI

Docker Pulls Image Size

Enterprise-Grade AI/ML Model Security Scanner

v4.0.1 — Proper ML-BOM Support | 99%+ False-Positive Reduction | Context-Aware Gating

Website⁠ | GitHub⁠ | Support⁠ | Documentation⁠ | Release Notes⁠

⁠Overview

Hex is an enterprise-grade security scanner specifically designed for AI/ML models, providing comprehensive protection against supply chain attacks, vulnerabilities, and compliance violations.

⁠Proper ML-BOM / SBOM generation (new inventory pipeline)

Model-card-aware inventory pass (pkg/sbom/inventory.go) that walks HuggingFace-style directories, parses README.md YAML frontmatter, reads config.json / generation_config.json, hashes files in parallel, and emits structured components.
CycloneDX 1.5 output with the native machine-learning-model component type, stable pkg:huggingface/<name>@<rev> bom-refs, purl-based linkage, and vulnerabilities[] with affects[].ref linking each CVE to its actual package component (not the root).
SPDX 2.3 output with semantically correct relationships (CONTAINS for weights/configs/tokenisers, DEPENDS_ON for framework libraries, GENERATED_FROM for base models, HAS_PREREQUISITE for datasets) and PACKAGE-MANAGER/purl external references.
CycloneDX-VEX companion automatically emitted alongside SPDX output (since SPDX 2.3 cannot natively carry vulnerabilities).
Parallel SHA-256 hashing with configurable ceiling (--sbom-max-hash-mb, default 2048) and opt-out (--sbom-no-hashes); verified against shasum -a 256 for files up to 670 MB.
Framework dependency inference: safetensors → pkg:pypi/safetensors, .onnx → pkg:pypi/onnxruntime, .bin/.pt → pkg:pypi/torch, .h5/.pb/.tflite → pkg:pypi/tensorflow/tflite-runtime, .msgpack → pkg:pypi/flax, .ot → pkg:cargo/rust-bert, plus a pinned transformers@<version> from config.json.
Git-LFS provenance: extracts the committed HEAD SHA from the scan target's .git/ tree and surfaces it both as a component property and as the model version.

⁠Key Features

⁠Comprehensive Security Coverage (30 Scanner Modules)

⁠Core Security Features

Supply Chain Security: Detects vulnerable dependencies, malicious packages, and compromised models
Adversarial Robustness: Analyzes model resilience against adversarial attacks (FGSM, PGD, Lipschitz continuity)
Backdoor Detection: Identifies hidden backdoors and trigger patterns using Neural Cleanse and activation analysis
Data Privacy: Detects PII leakage, model inversion risks, and memorization vulnerabilities
LLM Security: Protects against prompt injection, jailbreaks, and excessive agency risks
License Compliance: Ensures GPL compliance and license compatibility

⁠Advanced AI/ML Security Features (NEW)

Model Poisoning Detection: Identifies data poisoning, gradient poisoning, and label flipping attacks in training datasets
Federated Learning Security: Detects Byzantine attacks, aggregation tampering, and client authentication issues
Model Extraction Prevention: Monitors API query patterns and detects model stealing attempts
Differential Privacy Verification: Validates privacy budget, noise calibration, and membership inference resistance
Explainability Attack Detection: Identifies SHAP/LIME manipulation and saliency map poisoning
Model Watermarking & Fingerprinting: Detects embedded watermarks and verifies model ownership
Quantization Security: Identifies bit-flip attacks and compression-induced vulnerabilities
Multi-Modal Security: Protects against cross-modal injection and alignment manipulation
RAG Security: Detects knowledge base poisoning, vector DB manipulation, and context injection
Model Drift Monitoring: Tracks performance degradation and concept drift
Homomorphic Encryption Compatibility: Verifies FHE readiness and encrypted inference support
Zero-Knowledge Proof Integration: Validates privacy-preserving audit trails
Synthetic Data Detection: Identifies AI-generated training data and deepfakes
Model Behavior Anomaly Detection: Monitors runtime anomalies and unexpected outputs
Supply Chain Provenance: Blockchain-based lineage tracking and tamper detection
Regulatory Compliance: GDPR/CCPA compliance, EU AI Act readiness, bias auditing
Edge Deployment Security: Verifies model obfuscation and side-channel resistance
AutoML Security: Detects NAS poisoning and hyperparameter manipulation

⁠Advanced Detection Capabilities

Model Discovery: Automatically identifies 15+ ML model formats (.safetensors, .pth, .onnx, .bin, .h5, .pkl, .joblib, .tf, .tflite, .mlmodel, .pt, .model, .weights, .caffemodel, .pb)
Pickle Security: Deep inspection of pickle files for arbitrary code execution risks
Entropy Analysis: Statistical analysis to detect hidden malicious payloads
Signature Verification: Cryptographic verification of model integrity
Model Card Extraction: Automatic parsing of README.md, config.json, and model_card.md files
Training Metadata: Captures framework versions, hyperparameters, and architecture details
Dataset Provenance: Tracks data sources, preprocessing steps, and ethical reviews
Real-time CVE Database: Live vulnerability feeds from NVD and OSV databases
CVSS v3.1 Scoring: Industry-standard vulnerability scoring with EPSS integration

⁠Enterprise Features

SBOM Generation: Multi-format support (JSON, CycloneDX, SPDX 2.3) with AI/ML metadata
AI/ML Model Cards: Automatic extraction of model documentation and metadata
Training Provenance: Captures training framework, parameters, and device information
Dataset Lineage: Tracks dataset sources, licenses, and preprocessing details
Supply Chain Attestations: SLSA and in-toto attestation support
Multiple Output Formats: JSON, SARIF, Table, Text, XML for CI/CD integration
Configurable Scanning: Granular control over scan depth and timeout settings
Finding Deduplication: Intelligent tracking to prevent duplicate alerts
Parallel Processing: Multi-threaded scanning with configurable worker pools
Low False Positives: Advanced heuristics minimize alert fatigue

⁠Quick Start

⁠Basic Usage

# Scan a HuggingFace model directory
docker run --rm -v $(pwd):/scan:ro layerd/hex:4.0.1 /scan --clear

# Clean, spec-compliant CycloneDX 1.5 ML-BOM
mkdir -p output && chmod 777 output
docker run --rm \
  -v $(pwd):/scan:ro -v $(pwd)/output:/output \
  layerd/hex:4.0.1 /scan --clear \
  --sbom /output/sbom.cdx.json --sbom-format cyclonedx

# SPDX 2.3 SBOM + automatic CycloneDX-VEX companion (vulns alongside)
docker run --rm \
  -v $(pwd):/scan:ro -v $(pwd)/output:/output \
  layerd/hex:4.0.1 /scan --clear \
  --sbom /output/sbom.spdx.json --sbom-format spdx

# Machine-readable JSON scan report
docker run --rm -v $(pwd):/scan:ro layerd/hex:4.0.1 /scan --json > report.json

# Skip specific scanner modules
docker run --rm -v $(pwd):/scan:ro layerd/hex:4.0.1 /scan \
  --skip pickle-detector,entropy-analyzer --verbose

# Fast SBOM for CI (no hashing)
docker run --rm \
  -v $(pwd):/scan:ro -v $(pwd)/output:/output \
  layerd/hex:4.0.1 /scan --clear \
  --sbom /output/sbom.cdx.json --sbom-format cyclonedx --sbom-no-hashes

⁠Production Deployment

# Scan with security options enabled
docker run --rm \
  --security-opt=no-new-privileges:true \
  --cap-drop=ALL \
  --read-only \
  -v $(pwd):/scan:ro \
  layerd/hex:latest /scan --verbose

# Generate SBOM for compliance (JSON format with AI/ML metadata)
docker run --rm \
  -v $(pwd):/scan:ro \
  -v $(pwd)/output:/output \
  layerd/hex:latest /scan --sbom /output/sbom.json

# Generate SBOM in SPDX format (ISO/IEC 5962:2021 standard)
docker run --rm \
  -v $(pwd):/scan:ro \
  -v $(pwd)/output:/output \
  layerd/hex:latest /scan --sbom /output/sbom.spdx.json --sbom-format spdx

# Generate SBOM in CycloneDX format with ML-MODEL components
docker run --rm \
  -v $(pwd):/scan:ro \
  -v $(pwd)/output:/output \
  layerd/hex:latest /scan --sbom /output/sbom.cdx.json --sbom-format cyclonedx

# CI/CD Integration with timeout
docker run --rm \
  -v $(pwd):/scan:ro \
  -e HEX_TIMEOUT=600 \
  layerd/hex:latest /scan --format json --output /scan/results.json

⁠Installation

⁠Docker (Recommended)

# Pull the latest image
docker pull layerd/hex:latest

# Run a scan
docker run --rm -v $(pwd):/scan:ro layerd/hex:latest /scan

⁠Configuration Options

⁠Command Line Arguments

Flag	Description	Default
`--verbose, -v`	Enable detailed output	false
`--recursive, -r`	Scan directories recursively	true
`--workers, -w`	Number of parallel workers	4
`--timeout`	Scan timeout in seconds	300
`--format, -f`	Output format (text/json/table)	text
`--output, -o`	Output file path	stdout
`--sbom`	Generate SBOM with AI/ML metadata	-
`--sbom-format`	SBOM format (json/spdx/cyclonedx)	json
`--sbom-no-hashes`	Skip SHA-256 hashing of model artifact files (fast)	false
`--sbom-max-hash-mb`	Skip hashing files larger than this size (MB)	2048
`--skip`	Skip specific scanner modules (comma-separated)	-
`--all-scanners`	Run ALL 30 scanners (bypass the pre-trained model gate — produces more findings including inherent-ML-property observations)	false
`--clear`	Clear previous scan findings before running	false
`--json`	Shorthand for --format json	false

Note on the "Scanners: N active" banner. Hex ships 30 scanner modules. When it detects a published pre-trained model (HuggingFace-style directory with config.json + tokenizer + weights), 20 of those scanners are skipped by default because their checks describe training-pipeline or deployment-runtime defenses that aren't meaningful against a static model snapshot — running them produces mostly false positives. The banner reports this as Scanners: 10 active (20/30 skipped — not applicable to pre-trained model; use --all-scanners to override). Pass --all-scanners to force everything to run; the --verbose flag lists every skipped module by name.

⁠Environment Variables

Variable	Description	Default
`HEX_TIMEOUT`	Global timeout override	300
`HEX_VERBOSE`	Enable verbose logging	false
`HEX_WORKERS`	Worker pool size	4
`NO_COLOR`	Disable colored output	false

⁠Docker Compose Integration

version: '3.8'

services:
  hex-scanner:
    image: layerd/hex:latest
    volumes:
      - ./models:/scan:ro
      - ./reports:/output
    environment:
      - HEX_VERBOSE=true
      - HEX_TIMEOUT=600
    command: ["/scan", "--json", "--output", "/output/report.json"]
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    read_only: true
    user: "1000:1000"

⁠CI/CD Integration

⁠GitHub Actions

- name: Security Scan with Hex
  uses: docker://layerd/hex:latest
  with:
    args: /github/workspace --json --output scan-results.json

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

⁠GitLab CI

security_scan:
  image: layerd/hex:latest
  script:
    - hex . --json > security-report.json
  artifacts:
    reports:
      security: security-report.json

⁠Jenkins Pipeline

stage('Security Scan') {
  agent {
    docker {
      image 'layerd/hex:latest'
      args '-v $WORKSPACE:/scan:ro'
    }
  }
  steps {
    sh 'hex /scan --json --output /scan/hex-report.json'
    archiveArtifacts 'hex-report.json'
  }
}

⁠Security Compliance

⁠Container Security

Non-root execution: Runs as UID 1000 (hex user)
Read-only filesystem: Supports read-only root filesystem
Minimal attack surface: Alpine-based image (~64MB)
No shell access: Security-hardened container
Signed images: Cosign signatures for authenticity
Regular updates: Weekly vulnerability scans and patches

⁠Compliance Standards

CWE Coverage: Maps to 50+ Common Weakness Enumerations
OWASP Top 10: Addresses AI/ML specific security risks
NIST AI RMF: Aligns with NIST AI Risk Management Framework
EU AI Act: Supports compliance requirements
SOC 2: Audit-ready security controls

⁠Advanced Usage

⁠AI/ML Metadata Extraction

# Extract model card and training information
docker run --rm -v $(pwd):/scan:ro \
  layerd/hex:latest /scan \
  --sbom model-metadata.json

# Generate SPDX SBOM with full AI/ML provenance
docker run --rm -v $(pwd):/scan:ro \
  layerd/hex:latest /scan \
  --sbom-format spdx \
  --sbom model-provenance.spdx.json

⁠Vulnerability Database Updates

# Update vulnerability database
docker run --rm \
  -v hex-data:/home/hex/.layerd/hex \
  layerd/hex:latest vulnfetch fetch

# Schedule automatic updates (cron)
0 */6 * * * docker run -v hex-data:/home/hex/.layerd/hex layerd/hex:latest vulnfetch fetch

⁠Custom Scanner Configuration

# Skip specific scanners
docker run --rm -v $(pwd):/scan:ro \
  layerd/hex:latest /scan \
  --skip entropy,metadata

# Focus on critical vulnerabilities only
docker run --rm -v $(pwd):/scan:ro \
  layerd/hex:latest /scan \
  --severity critical,high

⁠Batch Processing

# Scan multiple directories with SBOM generation
for dir in model1 model2 model3; do
  docker run --rm -v $(pwd)/$dir:/scan:ro \
    layerd/hex:latest /scan \
    --json > results-$dir.json \
    --sbom sbom-$dir.json
done

⁠Output Examples

⁠JSON Output Structure

{
  "summary": {
    "total_issues": 15,
    "critical": 2,
    "high": 5,
    "medium": 6,
    "low": 2,
    "security_score": 72,
    "security_grade": "C",
    "verdict": "UNSAFE - High severity vulnerabilities detected"
  },
  "results": [
    {
      "id": "CVE-2023-45857",
      "type": "vulnerability",
      "severity": "CRITICAL",
      "title": "Arbitrary code execution in pickle file",
      "description": "Unsafe deserialization vulnerability",
      "file_path": "/scan/model.pkl",
      "line_number": 42,
      "confidence": 0.95,
      "cvss": {
        "version": "3.1",
        "vector_string": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
        "base_score": 9.8,
        "base_severity": "CRITICAL"
      },
      "cwe": ["CWE-502"],
      "remediation": "Avoid using pickle files or implement secure deserialization",
      "references": [
        "https://nvd.nist.gov/vuln/detail/CVE-2023-45857"
      ]
    }
  ]
}

⁠Command Line Output

╔══════════════════════════════════════════╗
║       Hex AI Model Scanner v1.0.0        ║
║            by Layerd AI                  ║
║       https://hex.layerd.com            ║
╚══════════════════════════════════════════╝

Scanning: /models/production
Mode: Directory
Scanners: 12 active (including AI/ML metadata)
Workers: 4

Scanning 100% [========================================]

Scan Summary
──────────────────────────────────────────
Total Issues: 5
  ● Critical: 1 (CVE-2023-25801)
  ● High: 2 (CVE-2022-45907, CVE-2022-35934)
  ● Medium: 2 (CVE-2021-41495)

Security Score: B (85/100)
Verdict: UNSAFE - High severity vulnerabilities detected

[1] Vulnerable package: tensorflow CVE-2023-25801
    CVSS: 9.8 (v3.1) - Critical
    CWE: CWE-190, CWE-787
    Fix: Update to tensorflow 2.11.1 or later

⁠Performance Benchmarks

Model Size	Files	Scan Time	Memory Usage
< 100 MB	10	~5 seconds	< 50 MB
100 MB - 1 GB	50	~30 seconds	< 100 MB
1 GB - 10 GB	100	~2 minutes	< 200 MB
> 10 GB	500+	~10 minutes	< 500 MB

⁠Architecture

Hex v2.1+ features 30 specialized security scanners organized in a modular architecture:

┌──────────────────────────────────────────────────┐
│             Hex Scanner Core v2.1+              │
├──────────────────────────────────────────────────┤
│                Core Scanners                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │Discovery │  │  Pickle  │  │ Manifest │     │
│  │ Engine   │  │ Detector │  │ Scanner  │     │
│  └──────────┘  └──────────┘  └──────────┘     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │Entropy   │  │Metadata  │  │Signature │     │
│  │Analyzer  │  │Inspector │  │Verifier  │     │
│  └──────────┘  └──────────┘  └──────────┘     │
├──────────────────────────────────────────────────┤
│            Security Scanners                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │Adversarial│ │ Backdoor │  │   LLM    │     │
│  │Robustness│ │ Detector │  │ Security │     │
│  └──────────┘  └──────────┘  └──────────┘     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │ Privacy  │  │ License  │  │Model Card│     │
│  │ Leakage  │  │Compliance│  │Extractor │     │
│  └──────────┘  └──────────┘  └──────────┘     │
├──────────────────────────────────────────────────┤
│        Advanced AI Security (NEW)                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │Poisoning │  │Federated │  │   RAG    │     │
│  │Detection │  │ Learning │  │ Security │     │
│  └──────────┘  └──────────┘  └──────────┘     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │Extraction│  │Differential│ │Explainability│ │
│  │Prevention│  │ Privacy  │  │  Attack   │     │
│  └──────────┘  └──────────┘  └──────────┘     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │Watermark │  │Quantization│ │Multi-Modal│    │
│  │Detection │  │ Security │  │ Security  │     │
│  └──────────┘  └──────────┘  └──────────┘     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │  Drift   │  │Homomorphic│ │ ZK Proof │     │
│  │ Monitor  │  │Encryption│  │Integration│     │
│  └──────────┘  └──────────┘  └──────────┘     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │Synthetic │  │ Behavior │  │Provenance│     │
│  │   Data   │  │ Anomaly  │  │ Tracking │     │
│  └──────────┘  └──────────┘  └──────────┘     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │Regulatory│  │   Edge   │  │  AutoML  │     │
│  │Compliance│  │ Security │  │ Security │     │
│  └──────────┘  └──────────┘  └──────────┘     │
├──────────────────────────────────────────────────┤
│         Vulnerability Database                   │
│      (CVE, CVSS, CWE, EPSS Data)               │
├──────────────────────────────────────────────────┤
│       AI/ML Metadata Enrichment                  │
│    (Training Info, Model Cards, SBOM)           │
└──────────────────────────────────────────────────┘

⁠Supply Chain Security

Hex Docker images include comprehensive supply chain attestations:

SLSA Provenance: Build provenance with source verification
SBOM Attestation: Complete dependency inventory in CycloneDX format
Cosign Signatures: Keyless signing via Sigstore for authenticity

Verify image authenticity:

cosign verify layerd/hex:latest \
  --certificate-identity-regexp "https://github.com/Layerd-AI/layerd-hex" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

⁠Troubleshooting

⁠Common Issues

# Permission denied errors
docker run --rm -v $(pwd):/scan:ro --user $(id -u):$(id -g) layerd/hex:latest /scan

# Timeout on large files
docker run --rm -v $(pwd):/scan:ro -e HEX_TIMEOUT=1800 layerd/hex:latest /scan

# Memory constraints
docker run --rm -m 1g -v $(pwd):/scan:ro layerd/hex:latest /scan

⁠Support and Resources

⁠Documentation

Full Documentation: https://hex.layerd.com/docs⁠

⁠Support Channels

Enterprise Support: [email protected]⁠
GitHub Issues: https://github.com/Layerd-AI/Hex/issues⁠

⁠Licensing

This project is licensed under the Apache 2.0 License with the Commons Clause.

What this means:

Permitted:

You are free to use this scanner for personal use, internal business auditing, and research.
You can modify and distribute the code.
You can use it for security audits and compliance checks.

Not permitted:

You are prohibited from selling this software or providing it as a commercial SaaS/service.
You cannot offer hosting or consulting services where the primary value comes from this software.

For enterprise licensing or commercial integration, please contact: [email protected]⁠.

See the LICENSE⁠ file for full legal terms.

⁠Contributing

We welcome contributions. Please see our Contributing Guide⁠ for details on filing issues, submitting pull requests, coding conventions, and the development workflow.

⁠About Layerd AI

Layerd AI is a leader in AI/ML security, providing enterprise-grade solutions for securing the AI supply chain.

Visit https://hex.layerd.com⁠ to learn more.

Tag summary

Recent tags

Content type

Image

Digest

sha256:619071975…

Size

23 MB

Last updated

5 months ago

docker pull layerd/hex