# snyk-labs/github-actions-scanner architecture

> Architecture diagram of the GitHub repository snyk-labs/github-actions-scanner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/snyk-labs/github-actions-scanner
- Repository: https://github.com/snyk-labs/github-actions-scanner

## Overview

##### Main Components

a) Core Scanner Engine:
- Represented by `lib/scanner.mjs`
- This is the main orchestrator of the scanning process

b) Rule Engine:
- This as a major component connected to the scanner
- Rule system (`lib/rules/`) with individual rule implementations
- Common utilities shared between rules (`lib/rules/common/`)

c) Input Processing:
- Different input methods:
- Single repository scanning
- Organization-wide scanning
- Action list scanning
- Clone functionality

d) Output Handling:
- Output processing system (`lib/outputHandler.mjs`)
- Different output formats (JSON and text)

##### Component Relationships

**Input Sources → Scanner Engine → Rule Engine → Output Handler**
- ↓
- Git Cloning
- (lib/clone.mjs)

##### Detailed Design Elements

- CMD_EXEC
- CODE_INJECTION
- PWN_REQUEST
- REPOJACKABLE
- UNPINNED_ACTION
- WORKFLOW_RUN
- UNSAFE_INPUT_ASSIGN

##### Flow Representation

Scanning process flow:
**1. Input Reception → 2. Repository Cloning → 3. Action Analysis → 4. Rule Application → 5. Finding Generation → 6. Output Formatting**

##### External Dependencies
- GitHub API integration
- Environment configuration handling

**Top Layer: User Interface (CLI Commands)**
**↓**
**Middle Layer: Scanner Core + Rule Engine**
**↓**
**Bottom Layer: GitHub Integration + File System Operations**

##### Additional Elements

- Different node types
- Connection types (data flow vs. control flow)
- Rule severity levels

##### Technical Details to Highlight

- Async operation flows
- Rule evaluation pipeline
- Finding generation process
- Output format transformation

Remember to:
- Keep the abstraction level appropriate for a security scanning tool
- Extensibility of the rule system
- Clear boundaries between scanning, rule processing, and output generation
- Error handling flows

- Nested components
- Directional flows
- Clear labeling
- Export to common formats

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Input
        SingleRepo[Single Repository]
        OrgWide[Organization-wide]
        ActionList[Action List]
    end

    subgraph "Core Processing"
        Scanner["Scanner Engine"]:::core
        GitClone["Git Cloning"]:::utility
        ActionProc["Action Processing"]:::utility
    end

    subgraph "Rule Engine"
        RuleEngine["Rule Engine"]:::core
        
        subgraph "Security Rules"
            CMD["Command Execution"]:::rule
            CODE["Code Injection"]:::rule
            PWN["PWN Request"]:::rule
            REPO["Repojackable"]:::rule
            UNPIN["Unpinned Action"]:::rule
            WORKFLOW["Workflow Run"]:::rule
            UNSAFE["Unsafe Input"]:::rule
        end

        subgraph "Rule Utilities"
            Finding["Finding Generation"]:::utility
            RuleMatcher["Rule Matcher"]:::utility
            CommonDefs["Common Definitions"]:::utility
        end
    end

    subgraph "Output Layer"
        OutputHandler["Output Handler"]:::output
        JSON[JSON Format]:::output
        Text[Text Format]:::output
    end

    subgraph External
        GitHubAPI["GitHub API"]:::external
    end

    %% Connections
    SingleRepo & OrgWide & ActionList --> Scanner
    Scanner --> GitClone
    Scanner --> ActionProc
    Scanner --> RuleEngine
    GitClone --> GitHubAPI
    ActionProc --> RuleEngine
    
    RuleEngine --> CMD & CODE & PWN & REPO & UNPIN & WORKFLOW & UNSAFE
    RuleEngine --- Finding & RuleMatcher & CommonDefs
    
    CMD & CODE & PWN & REPO & UNPIN & WORKFLOW & UNSAFE --> OutputHandler
    OutputHandler --> JSON & Text

    %% Styling
    classDef core fill:#3498db,stroke:#2980b9,color:white
    classDef rule fill:#e74c3c,stroke:#c0392b,color:white
    classDef utility fill:#f1c40f,stroke:#f39c12,color:black
    classDef output fill:#2ecc71,stroke:#27ae60,color:white
    classDef external fill:#9b59b6,stroke:#8e44ad,color:white

    %% Click Events
    click Scanner "https://github.com/snyk-labs/github-actions-scanner/blob/main/lib/scanner.mjs"
    click RuleEngine "https://github.com/snyk-labs/github-actions-scanner/tree/main/lib/rules/"
    click CMD "https://github.com/snyk-labs/github-actions-scanner/blob/main/lib/rules/cmd_exec.mjs"
    click CODE "https://github.com/snyk-labs/github-actions-scanner/blob/main/lib/rules/code_injection.mjs"
    click PWN "https://github.com/snyk-labs/github-actions-scanner/blob/main/lib/rules/pwn_request.mjs"
    click REPO "https://github.com/snyk-labs/github-actions-scanner/blob/main/lib/rules/repojackable.mjs"
    click UNPIN "https://github.com/snyk-labs/github-actions-scanner/blob/main/lib/rules/unpinned_action.mjs"
    click WORKFLOW "https://github.com/snyk-labs/github-actions-scanner/blob/main/lib/rules/workflow_run.mjs"
    click UNSAFE "https://github.com/snyk-labs/github-actions-scanner/blob/main/lib/rules/unsafe_input_assign.mjs"
    click GitClone "https://github.com/snyk-labs/github-actions-scanner/blob/main/lib/clone.mjs"
    click ActionProc "https://github.com/snyk-labs/github-actions-scanner/blob/main/lib/actions.mjs"
    click OutputHandler "https://github.com/snyk-labs/github-actions-scanner/blob/main/lib/outputHandler.mjs"
    click Finding "https://github.com/snyk-labs/github-actions-scanner/blob/main/lib/rules/common/finding.mjs"
    click RuleMatcher "https://github.com/snyk-labs/github-actions-scanner/blob/main/lib/rules/common/utils.mjs"
    click CommonDefs "https://github.com/snyk-labs/github-actions-scanner/blob/main/lib/rules/common/defs.mjs"
```
