> ## Documentation Index > Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt > Use this file to discover all available pages before exploring further. # End-to-End Workflow > Set up SCANOSS pre-commit hooks to catch undeclared open source components before code leaves your workstation, integrate the GitHub Actions workflow to enforce copyleft and undeclared-component policies on pull requests, and use Dependency Track to manage vulnerabilities and define organisational licence policies. ## Workflow Overview ```mermaid theme={null} graph TD Developer[Developer] Developer -->|On Commit| Hooks["SCANOSS Pre-Commit Hooks"] DeclareComponents -->|Command Line| InstallPY[SCANOSS-PY] DeclareComponents -->|Desktop GUI| InstallCC[SCANOSS-CC] InstallPY --> ReCommit[Developer Re-Commits Code] InstallCC --> ReCommit ReCommit --> Hooks Hooks --> GitCommit{Pre-Commit Scan Passed?} GitCommit -->|Yes| CISetup[Setup Github Actions Workflow] GitCommit -->|No| Understand[Understanding the Results] Understand --> DeclareComponents %% CI PIPELINE CISetup --> Secrets[Setup GitHub Secrets] Secrets --> Trigger[Trigger SCANOSS GitHub Workflow] Trigger --> GHResults[Review GitHub Actions Summary] GHResults --> DependencyTrack[Analyse in Dependency Track] DependencyTrack --> Decision{Policy Status} Decision -->|Workflow Violations| FixWorkflow[Fix Issues from Report] Decision -->|Passed| Merge[Merge Pull Request] FixWorkflow --> Trigger %% Links click Hooks "#setup-pre-commit-hooks" click Understand "#understanding-the-results" click DeclareComponents "#declare-components" click InstallPY "#scanoss-py" click InstallCC "#scanoss-cc" click CISetup "#github-actions-workflow" click Secrets "#configure-github-secrets" click Trigger "#trigger-your-first-workflow-run" click GHResults "#review-pipeline-summary" click DependencyTrack "#access-dependency-track-dashboard" %% Styling style Developer fill:#42A5F5,stroke:#1976D2,stroke-width:3px,color:#fff style Hooks fill:#7E57C2,stroke:#5E35B1,stroke-width:3px,color:#fff style DeclareComponents fill:#42A5F5,stroke:#1976D2,stroke-width:2px,color:#fff style InstallPY fill:#26A69A,stroke:#00897B,stroke-width:2px,color:#fff style InstallCC fill:#26A69A,stroke:#00897B,stroke-width:2px,color:#fff style ReCommit fill:#42A5F5,stroke:#1565C0,stroke-width:2px,color:#fff style GitCommit fill:#42A5F5,stroke:#1976D2,stroke-width:2px,color:#fff style Understand fill:#FF9800,stroke:#F57C00,stroke-width:2px,color:#fff style CISetup fill:#66BB6A,stroke:#43A047,stroke-width:3px,color:#fff style Secrets fill:#FFA726,stroke:#F57C00,stroke-width:2px,color:#fff style Trigger fill:#78909C,stroke:#546E7A,stroke-width:2px,color:#fff style GHResults fill:#FF9800,stroke:#F57C00,stroke-width:3px,color:#fff style DependencyTrack fill:#AB47BC,stroke:#8E24AA,stroke-width:2px,color:#fff style Decision fill:#42A5F5,stroke:#1976D2,stroke-width:2px,color:#fff style FixWorkflow fill:#EF5350,stroke:#E53935,stroke-width:2px,color:#fff style Merge fill:#66BB6A,stroke:#43A047,stroke-width:3px,color:#fff ``` ## Workflow Process 1. This workflow begins when a developer attempts to commit code to the repository. The commit operation automatically triggers the SCANOSS pre-commit hook, ensuring that SCANOSS checks are performed before code leaves the developer workstation. 2. The SCANOSS pre-commit hook performs a scan of the repository contents and evaluates whether all detected open source components have been properly declared. 3. When the scan identifies undeclared components, SCANOSS provides feedback describing the findings. 4. After reviewing the scan output, developers must declare any missing components. 5. Following component declaration, the developer performs another commit. This commit re-triggers the SCANOSS pre-commit hook, allowing the updated declarations to be validated. 6. When the pre-commit scan passes successfully, the code can be pushed to the remote repository. 7. A repository push triggers the SCANOSS GitHub Actions workflow. 8. Following workflow execution, results are analysed within Dependency Track and evaluated against organisational policy requirements. 9. Once all policy checks have passed, the pull request is eligible for merge. ## Prerequisites Before you begin, ensure you have: * [Python 3.9](https://www.python.org/) or later * [Git](https://git-scm.com/) installed and configured * GitHub repository with Actions enabled and workflow permissions configured * SCANOSS API key for enterprise features * Dependency Track API Key and URL ## Setup Pre-Commit Hooks SCANOSS Pre-Commit Hooks ensures that before you push any code to your repository, SCANOSS automatically checks for undeclared open source components. This shift-left approach helps you catch compliance issues early in the development process, before code reaches your team or production. ### Install Pre-Commit Framework Open your terminal or command prompt and install the pre-commit framework: ```bash theme={null} pip install pre-commit ``` ### Configure the Hook Navigate to your project root directory and create a new file named `.pre-commit-config.yaml`. Add the following configuration to the file: ```yaml theme={null} repos: - repo: https://github.com/scanoss/pre-commit-hooks rev: v0.4.0 # Use the latest version from https://github.com/scanoss/pre-commit-hooks/releases hooks: - id: scanoss-check-undeclared-code ``` **Verify Configuration:** In your terminal, navigate to your project directory and run: ```bash theme={null} pre-commit validate-config ``` This confirms your configuration file is valid. ### Install the Hook In your terminal, while still in your project directory, run: ```bash theme={null} pre-commit install ``` This installs the hook into your `.git/hooks` directory. Once installed, the hook runs automatically before every `git commit`. You should see output like: ```bash theme={null} pre-commit installed at .git/hooks/pre-commit ``` ### Configure Environment Variables Open your IDE or text editor and create a new file named `.env` in your project root directory. Add your configuration: ```bash theme={null} # .env SCANOSS_API_KEY=your_api_key_here SCANOSS_DEBUG=true ``` **Save the file** in your project root directory. The hook will automatically load these variables during execution. ### Configure .gitignore Before committing, you need to configure your `.gitignore` file to exclude SCANOSS generated files from version control. Open your `.gitignore` file (or create one if it doesn't exist) in your project root and add: ```gitignore theme={null} # SCANOSS temporary files and cache *.wfp .scanoss/ .env ``` Save the `.gitignore` file in your project root directory. ## Commit Changes Now test the hook to ensure it's working correctly. **Stage your files:** ```bash theme={null} git add . ``` **Attempt a commit:** ```bash theme={null} git commit -m "Testing Pre-Commit Hooks" ``` The hook runs automatically and scans your staged files. ### Undeclared Components If undeclared components are found, the commit will be **blocked** and you'll see a summary table in your terminal: ```bash theme={null} SCANOSS Undeclared Check.................................................Failed - hook id: scanoss-check-undeclared-code - duration: 7.75s - exit code: 1 SCANOSS detected 2 files containing potential Open Source Software: ┌──────────────┬─────────┬────────────┬─────────┬──────────────┬──────────────┐ │ File │ Status │ Match Type │ Matched │ Purl │ License │ ├──────────────┼─────────┼────────────┼─────────┼──────────────┼──────────────┤ │ src/copyrig… │ pending │ snippet │ 95% │ pkg:github/… │ GPL-2.0-only │ ├──────────────┼─────────┼────────────┼─────────┼──────────────┼──────────────┤ │ src/scanner… │ pending │ snippet │ 96% │ pkg:github/… │ MIT │ └──────────────┴─────────┴────────────┴─────────┴──────────────┴──────────────┘ Run 'scanoss-cc' in the terminal to view the results in more detail. ``` **What happened:** The pre-commit hook generated a summary table in your terminal and created a detailed scan results file at `.scanoss/results.json` in your project directory. **To resolve this:** The commit is blocked until you review the findings and declare the components. Follow the same workflow mentioned earlier: 1. **Review the results**: The detailed findings are in `.scanoss/results.json` See [Understanding the Results](end-to-end#understanding-the-results) to understand what each field means 2. **Declare the components**: Follow the [Declare Components](end-to-end#declare-components) section to properly declare the detected components 3. **Check in scanoss.json**: After updating `scanoss.json` with your component declarations, stage the file: ```bash theme={null} git add scanoss.json ``` 4. **Retry your commit**: Now retry the commit with your updated declarations: ```bash theme={null} git commit -m "Add new features" ``` ## Understanding the Results After running a scan, SCANOSS generates a `results.json` file containing all detected open source code in your project. The scan results are stored inside your project folder in a hidden directory named .scanoss. Look for the file: ```bash theme={null} /.scanoss/results.json ``` **Component Identification:** * **component**: Name of the detected open source component * **file**: The file in your project where open source code was detected * **file\_hash**: Unique identifier for the exact file content **Match Details:** * **id**: Match type - how the code was detected: * `snippet` - Part of a file matches known open source code * `file` - An entire file matches a known component * **matched**: Similarity percentage * **lines**: Line range in your file where the match was found * **oss\_lines**: Corresponding line range in the original open source component * **status**: Current state of the finding: * `pending` - Newly detected, needs your review * `identified` - Properly documented in your `scanoss.json` **Component Information:** * **vendor**: Component maintainer or organisation * **version**: Detected version * **latest**: Most recent available version * **url**: Repository URL * **purl**: Package URL * **release\_date**: When this version was released **License Information:** * **name**: License identifier * **copyleft**: Whether derivative works must use the same license * **patent\_hints**: Whether license contains patent clauses * **source**: Where license was detected: * `component_declared` - From the component's metadata * `file_spdx_tag` - From SPDX tags in the file * `license_file` - From a LICENSE file * `file_header` - From file header comments * **incompatible\_with**: Licenses that conflict with this one * **url**: Link to SPDX license definition * **checklist\_url**: Link to OSADL compliance checklist **Additional Data:** * **copyrights**: Copyright statements found in the code * **cryptography**: Cryptographic algorithms detected * **dependencies**: Dependencies declared in the component * **health**: Repository health metrics * **quality**: Code quality scores * **vulnerabilities**: Known CVEs affecting this component **What This Means for You:** Any finding marked as `"status": "pending"` requires a decision. Review the match and decide: * **Include** it in your `scanoss.json` to declare intentional use * **Dismiss** it if it's a false positive or your own code * **Replace** it if the license is incompatible with your project ## Declare Components After reviewing the scan results, you need to review and declare any detected components that have not yet been identified. Component declaration can be performed using either **SCANOSS-PY** or **SCANOSS-CC**. ### [SCANOSS-PY](https://github.com/scanoss/scanoss.py) To declare components using **SCANOSS-PY**, you must first install it. Follow the steps below in your terminal or command prompt. **Standard Installation:** ```bash theme={null} pip install scanoss ``` **Verify Installation:** ```bash theme={null} scanoss-py --version ``` If the installation worked, you’ll see the tool’s version number. **Step 1: Identify Undeclared Components** Use the inspect command to find components that need to be declared: ```bash theme={null} scanoss-py inspect undeclared -i ./scanoss/results.json ``` This will output suggested components to add to your `scanoss.json`: ```json theme={null} { "bom": { "include": [ { "purl": "pkg:github/scanoss/engine" }, { "purl": "pkg:github/scanoss/scanoss.py" } ] } } ``` **Step 2: Create scanoss.json** Using the output from Step 1, create a `scanoss.json` file in your project root directory (the same directory that was scanned). This configuration file controls scanning behavior and manages component declarations, and must be created manually. Add a `self` section to the scanoss.json file to include relevant project information. You can also expand the `bom.include` entries by adding comments for clarity. You can view a sample `scanoss.json` [schema](https://scanoss.github.io/schema/) using the following link. ```json theme={null} { "self": { "name": "my-project", "license": "MIT", "description": "My project" }, "bom": { "include": [ { "purl": "pkg:github/scanoss/engine", "comment": "SCANOSS engine for code analysis" }, { "purl": "pkg:github/scanoss/scanoss.py", "comment": "SCANOSS Python SDK for API integration" } ] } } ``` **Step 3: Rescan with Configuration** Run the scan again with your `scanoss.json` settings: ```bash theme={null} scanoss-py scan --key $SCANOSS_API_KEY --settings scanoss.json -o .scanoss/results.json /path/to/project ``` **Step 4: Validate Compliance** Verify all components are properly declared: ```bash theme={null} scanoss-py inspect undeclared -i .scnaoss/results.json ``` Successful output: ```bash theme={null} 0 undeclared component(s) were found. ``` Learn more about the [SCANOSS Settings file format](license-dataset/scanoss-settings) and [SCANOSS-PY](license-dataset/snippet-detection/scanoss-py). ### [SCANOSS-CC](https://github.com/scanoss/scanoss.cc) To declare components using **SCANOSS-CC**, you must also have [SCANOSS-PY](end-to-end#scanoss-py) installed, as it is a required dependency for **SCANOSS-CC** to function. Open your terminal (macOS/Linux) or PowerShell (Windows), then run the command appropriate for your operating system. **macOS / Linux:** ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/scanoss/scanoss.cc/main/scripts/install.sh | bash ``` **Windows (PowerShell as Administrator):** ```powershell theme={null} irm https://raw.githubusercontent.com/scanoss/scanoss.cc/main/scripts/install-windows.ps1 | iex ``` **Verify Installation:** ```bash theme={null} scanoss-cc --version ``` Before declaring components with **SCANOSS-CC**, configure your API credentials: ```bash theme={null} scanoss-cc configure --apiUrl https://api.scanoss.com --key $SCANOSS_API_KEY ``` Make sure you're in your project directory where the scan results are located: ```bash theme={null} cd /path/to/your/project ``` **SCANOSS-CC** will automatically load results from `.scanoss/results.json` in the current directory. Launch **SCANOSS-CC** to review results and make decisions interactively: ```bash theme={null} scanoss-cc ``` **In the SCANOSS-CC interface:** 1. **Review Results**: View side-by-side code comparisons showing your code matched against the detected open source component 2. **Make Decisions**: Use the action icons at the top of the dashboard to: * **Include**: Accept and declare the component as an intentional dependency * **Dismiss**: Mark as false positive or your own code * **Replace**: Flag for replacement with alternative code or different license * **Restore**: Undo a previous decision and return the finding to a pending state 3. **Save Changes**: Your decisions are saved to `scanoss.json` at your project root. Future scans will remember these decisions. **Keyboard Shortcuts:** View all shortcuts by selecting **Help** → **Keyboard Shortcuts** for faster decision-making. ### Commit Changes Now run the hook to verify that all components have been successfully declared. ```bash theme={null} git commit -m "Testing Pre-Commit Hooks" ``` If all components are declared the commit proceeds normally: ```bash theme={null} SCANOSS Undeclared Check.................................................Passed - hook id: scanoss-check-undeclared-code - duration: 5.32s [main 1a2b3c4] Add new features 2 files changed, 45 insertions(+), 3 deletions(-) ``` Your code is now safe to push to the repository! ## GitHub Actions Workflow [GitHub Actions](https://github.com/features/actions) provides automated workflows that run on specific events like pushes and pull requests. We'll create a workflow that scans your code on every change. ### Create Workflow Directory GitHub Actions expects workflow files to be stored in a specific location within your project. In the root of your project, create a folder named `.github` and inside it, create another folder called `workflows`. ```bash theme={null} your-project/ └── .github/ └── workflows/ ``` ### Create the Workflow File Create a file named `scanoss.yml` in the `.github/workflows` directory with the following configuration. The [SCANOSS Code Scan Action](https://github.com/scanoss/gha-code-scan) enhances your software development process by automatically scanning your code for security vulnerabilities and license compliance using configurable policies. ```yaml theme={null} name: SCANOSS with Dependency Track on: pull_request: branches: [main] permissions: contents: read pull-requests: write checks: write actions: read jobs: scanoss-code-scan: name: SCANOSS Code Scan runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v6 - name: Run SCANOSS Code Scan id: scanoss-code-scan-step uses: scanoss/gha-code-scan@v1 with: policies: copyleft, undeclared, depTrack scanMode: "full" dependencies.enabled: true deptrack.upload: true deptrack.url: ${{ secrets.DT_SERVER_URL }} deptrack.apikey: ${{ secrets.DT_API_KEY }} deptrack.projectname: "my-project" deptrack.projectversion: "1.0.0" api.key: ${{ secrets.SCANOSS_API_KEY }} - name: Print stdout scan command run: echo "${{ steps.scanoss-code-scan-step.outputs.stdout-scan-command }}" - name: Print Results run: cat "${{ steps.scanoss-code-scan-step.outputs.result-filepath }}" ``` **Key Workflow Features:** * Runs on pull requests to the `main` branch * Performs a full scan of your repository * Sends SBOM to Dependency Track for ongoing monitoring * Validates copyleft, undeclared components, and Dependency Track policies ### Understanding Workflow Triggers The workflow file above uses `on: pull_request: branches: [main]` to determine when SCANOSS runs. GitHub Actions workflows can be triggered by various [events](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow). ### Understanding Compliance Policies The workflow file uses `policies: undeclared,copyleft, depTrack` to enforce compliance rules. SCANOSS can enforce these policies to fail your workflow when issues are detected: * **`undeclared`** - Fails if open source components aren't declared in `scanoss.json` * **`copyleft`** - Fails if copyleft-licensed components are detected * **`depTrack`** - This policy integrates with [Dependency Track](https://dependencytrack.org/) to check for security vulnerabilities, license violations, and policy compliance ### Configure GitHub Secrets Now that you’ve configured the GitHub workflow file in your project, navigate to your GitHub repository and add the required secrets. **Settings → Secrets and variables → Actions** Click **New repository secret** and add each of the following: | Secret Name | Description | Example | | ----------------- | ------------------------- | ---------------------------------------------------------------------------- | | `DT_API_KEY` | Dependency Track API key | abc123... | | `DT_SERVER_URL` | Dependency Track base URL | [https://your-dependencytrack-url.com](https://your-dependencytrack-url.com) | | `SCANOSS_API_KEY` | SCANOSS API key | xyz789... | ### Trigger Your First Workflow Run Now that you've created your workflow file, let's push and trigger the scan. ```bash theme={null} # Push to your repository git push origin ``` ### Create a Pull Request 1. Go to your GitHub repository 2. You should see a prompt to **"Compare & pull request"** for your branch 3. Click **"Compare & pull request"** 4. Review the changes and click **"Create pull request"** ### Monitor the Workflow Execution Once you create the pull request, GitHub Actions will automatically trigger your workflow: 1. In your pull request, click the **"Checks"** tab 2. You should see your "**SCANOSS Scan**" workflow running 3. Click on the workflow to see real-time progress 4. Wait for the workflow to complete ### Review Pipeline Summary After the workflow completes, navigate to the **Summary** page to review results. summary-gha **Understanding the Summary:** * **Scan Report**: License distribution pie chart and detailed license table * **Policies**: Compliance check results (copyleft, undeclared, Dependency Track) * **Details**: Upload status with direct link to Dependency Track project * **Artifacts**: Downloadable reports, SBOMs and policy results ### Access Dependency Track Dashboard Once the scan uploads to Dependency Track, access the full dashboard for deeper analysis. In the pipeline summary's **Details** section, click the **View Project** link to open your project in Dependency Track. status-check dependency-track ### Explore Dashboard Sections The Dependency Track dashboard provides several key views for managing your open-source dependencies: * **Components**: Complete inventory of detected components with their licenses, versions, and risk scores * **Dependency Graph**: Visual representation of direct and transitive dependency relationships * **Audit Vulnerabilities**: List of all components with known security vulnerabilities, organized by severity ### Manage Vulnerabilities Click on any vulnerability to open its details panel and assess its actual risk. vulnerability-status **Analysis States:** * **Not Set** - Default state requiring review * **Exploitable** - Confirmed risk to your application * **In Triage** - Currently under investigation * **False Positive** - Doesn't apply to your usage * **Not Affected** - Your configuration isn't vulnerable * **Resolved** - Fixed (usually by upgrading) **To Manage a Vulnerability:** 1. Click the vulnerability in the **Audit Vulnerabilities** tab 2. Review the CVE details, affected versions and remediation advice 3. Select an analysis state from the dropdown 4. Add a comment explaining your decision 5. Click **Save** ### Define Organisational Policies While vulnerability management handles security threats reactively, policy management takes a proactive approach by defining rules that automatically identify compliance issues. Navigate to **Policy Management** from the main menu to create policies. #### Create License Policies **Block Specific Licenses:** 1. Click **Create Policy** 2. Add a **Condition** and select **License** 3. Choose the specific license to block (e.g., GPL-3.0) 4. Set violation state to **FAIL** 5. Save the policy **Block License Groups:** For broader control, create license groups: 1. Go to **License Groups** tab 2. Click **Create License Group** 3. Name it (e.g., "Copyleft Licenses") 4. Add licenses: GPL-2.0, GPL-3.0, AGPL-3.0 5. Save the group license-group Then create a policy using the group: 1. **Create Policy** → Add **Condition** 2. Select **License Group** 3. Choose your license group 4. Set violation state 5. Save the policy policy-management #### Create Vulnerability Policies **Flag High-Severity Vulnerabilities:** 1. Click **Create Policy** 2. Add a **Condition** and select **Severity** 3. Select severity levels: CRITICAL, HIGH 4. Set violation state to **FAIL** 5. Save the policy **Block Specific CVEs:** 1. Click **Create Policy** 2. Add a **Condition** and select **Vulnerability ID** 3. Enter CVE identifier (e.g., CVE-2024-1234) 4. Set violation state to **FAIL** 5. Save the policy #### Create Component Age Policies Flag outdated components that may lack security updates: 1. Click **Create Policy** 2. Add a **Condition** and select **Age** 3. Set operator to **greater than** 4. Specify age threshold in days 5. Set violation state to **WARN** 6. Save the policy ### Review Policy Violations Navigate to your project's **Policy Violations** tab to see all policy breaches: policy-violations-status **Violation States:** * **INFO** - Informational only, doesn't block releases * **WARN** - Requires review before release * **FAIL** - Must be resolved before release ### Triage Policy Violations When a violation is technically accurate but acceptable in your context: 1. Navigate to **Policy Violations** tab 2. Select the violation to triage 3. Click **Analysis** 4. Select an analysis state: * **Not Set** - No decision made yet * **Approved** - Reviewed and accepted as known exception * **Rejected** - Not accepted, requires remediation 5. Add a comment explaining the justification 6. Save your decision Triaged violations remain visible for audit purposes but no longer block releases when marked as **Approved**.