SecDim Sandbox 💎

SecDim Sandbox provides Just In Time (JIT) secure coding training labs based on the finding reported by majority of security scanning tool. It can also enrich the reported findings with link to related secure coding exercises.

Description

SecDim Sandbox command-line application provides two main functions:

• enrich: Parses a SARIF file, enriches each finding with links to SecDim Secure Coding exercises, and outputs an augmented SARIF file.

• jit: Manages Just-In-Time training games on the SecDim platform by creating or updating a game and adding relevant challenge slugs extracted from a SARIF file.

Both features can be used manually or integrated into CI/CD pipelines.

Installation

1. Ensure you have Go (>=1.20) installed: Go installation docs.

2. Clone this repository and navigate to the project root

3. Build the binary: make build

git clone https://github.com/secdim/sandbox-sarif-parser.git
cd sandbox-sarif-parser
make build

The compiled binary is bin/sandbox.

Usage

Enrich SARIF

Parse and enrich a SARIF file with SecDim Secure Coding labs

sandbox enrich --in <input.sarif> --out <output.sarif> [--tool <tool>]

• --tool is optional - specify semgrep, snyk, or codeql to override auto-detection

JIT Game Management

Extract challenge slugs from a SARIF file and either create or update a SecDim game

sandbox jit --game-slug <slug> [--new] --in <input.sarif>
            [--game-title <title>]
            [--game-desc <desc>]
            [--game-tags <t1,t2>]
            [--game-deps <d1,d2>]
            [--game-chals <c1, c2>]
            [--game-start <RFC3339>] [--game-end <RFC3339>]
            [--filter-by-language] [--tool <tool>]

• Add --new to create a fresh game (requires title, description, challenges, start/end).

• Omit --new to patch an existing game (will error if the game does not exist).

• Add --filter-by-language to filter challenges based on programming languages detected from the SARIF file. If this flag is not provided, all challenges matching any detected language will be included. We recommend using this flag to ensure the training content is relevant to the codebase.

• --tool is optional - specify semgrep, snyk, or codeql to override auto-detection

Example with language filtering:

sandbox jit --game-slug python-security-training --filter-by-language --in report.sarif

If the SARIF file contains Python vulnerabilities, only Python-related challenges will be added to the game.

Supported Tools

SecDim Sandbox supports SARIF files from various security scanning tools:

Fully Supported Tools

• Semgrep - Comprehensive rule parsing with intelligent search strategy:

  1. CWE search (highest priority for precise vulnerability matching)

  2. Free text search on rule names/descriptions (contextual relevance)

  3. OWASP search (broad category coverage as final fallback)

• Snyk Code - Rule-based vulnerability detection with metadata extraction

• CodeQL - GitHub’s semantic analysis engine with extension-based rules

Auto-Detection

The tool automatically detects the scanner type based on SARIF structure: - Driver name patterns (semgrep, snyk code, codeql) - Rule organization and metadata structure - Tool-specific SARIF formatting

Unsupported/Unknown Tools

For SARIF files from other tools (Bandit, ESLint, SonarQube, etc.): - The system detects them as "unknown tool" - Falls back to generic parsing using Semgrep-compatible logic - May still work if the SARIF structure includes standard fields like: - Rule IDs and descriptions - CWE tags in properties.tags (format: "CWE-79") - OWASP tags in properties.tags (format: "OWASP:A03")

Note: You can also explicitly specify the tool with --tool <tool> to override auto-detection. We will add support for more tools over time.

Environment Variables

Override defaults via environment variables (flags take precedence):

Variable	Description
SECDIM_API_KEY	API key for enrichment & game endpoints (required)
JIT_GAME_SLUG	Default game slug
JIT_GAME_TITLE	Default game title
JIT_GAME_DESC	Default game description
JIT_GAME_CHALS	Default game challenges
JIT_GAME_TAGS	Default game tags
JIT_GAME_DEPARTMENTS	Default game departments
JIT_GAME_START_TIME	Default start time
JIT_GAME_END_TIME	Default end time

Examples

Create a new training game and populate it with challenges

export SECDIM_API_KEY=XYZ
sandbox jit --new --game-slug just-in-time-training
             --game-title "Just-In-Time Training"
             --game-desc "Exercises based on reported vulnerabilities"
             --game-tags Trivial,Easy,Medium,Hard
             --game-start 2025-05-06T00:00:00Z
             --game-end   2025-06-06T00:00:00Z
             --game-chals "xsspy,xssjs"
             --in report.sarif
             --filter-by-language

Updating an existing game based on new vulnerabilities

sandbox jit --game-slug just-in-time-training --in report.sarif --filter-by-language

Working with unsupported tools

# For tools not directly supported, the system falls back to generic parsing
sandbox enrich --in bandit-report.sarif --out enriched-bandit.sarif

# You can also explicitly specify a compatible tool format for enrichment
sandbox enrich --in custom-tool.sarif --out enriched-custom.sarif --tool semgrep

# Force Semgrep-style parsing for JIT with unknown tools
sandbox jit --game-slug custom-training --tool semgrep --filter-by-language --in custom-tool.sarif

CI/CD Integration

In your GitHub Actions you can add steps like:

- name: Build
  run: make build

- name: Enrich SARIF
  run: sandbox enrich --in report.sarif --out enriched_report.sarif

- name: Update JIT Game with Language Filtering
  run: |
    export SECDIM_API_KEY=${{ secrets.SEC_DIM_API_KEY }}
    sandbox jit --game-slug language-specific-training --filter-by-language --in report.sarif