FOSSLight Scanner

FOSSLight Scanner is released under the Apache-2.0. Current python package version. GitHub Repository

FOSSLight Scanner is an integrated scanning tool that automatically analyzes open source information contained in dependencies, source code, and binaries. In addition to analyzing sources downloadable via Git or wget, it can also analyze sources provided through a local path, and the results are generated in the FOSSLight Report format, which follows the SBOM standard.

FOSSLight Scanner consists of the following 3 scanners, each responsible for different analysis areas.

  1. FOSSLight Dependency Scanner
    A scanner that analyzes dependencies used through package managers or build systems to extract open source information.
    It supports various package managers such as npm, pypi, maven, gradle, etc., and analyzes not only direct dependencies but also transitive dependencies that are included as a result.
  2. FOSSLight Source Scanner
    Detects open source-related information such as license phrases, copyright strings, and code snippets by analyzing source code.
  3. FOSSLight Binary Scanner
    Performs open source analysis on binary files.
    Instead of reverse engineering the binary itself, it collects binary lists and matches them with OSS information in the internal database to identify open source included in the binary.



Table of Contents



Prerequisites

  1. FOSSLight Scanner runs on Python 3.10 or higher (officially supported versions: 3.10~3.12) and can be installed via pip3 command.
  2. To analyze Jar files, Open Source JDK (Java) must be installed.
  3. (For Windows) Microsoft Build Tools (Microsoft Visual C++ 14.0+) must be installed.


Installation

Install from Bee (LGE Only)

You can install and use FOSSLight Scanner from Bee.

Standard Installation Method

FOSSLight Scanner can be installed using pip3.
It is recommended to install it in a python3 virtualenv environment.

$ pip3 install fosslight_scanner

Installation Error Cases

If the error β€˜Cargo, the Rust package manager, is not installed or is not on PATH.' occurs, install cargo and rust as described below, then reinstall FOSSLight Scanner.

  • Linux, macOS 
    $ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
$ export PATH="$HOME/.cargo/bin:$PATH"
  • Windows : Download the rust-init.exe file from https://www.rust-lang.org/tools/install and install it.

How to Run

How to run by mode & Parameters

    πŸ“– Usage
    ────────────────────────────────────────────────────────────────────
    fosslight [mode] [options] <arguments>

    πŸ“ Description
    ────────────────────────────────────────────────────────────────────
    FOSSLight Scanner performs comprehensive open source analysis by running
    multiple modes (Source, Dependency, Binary) together. It can download
    source code from URLs (git/wget) or analyze local paths, and generates
    results in OSS Report format.

    πŸ“š Guide: https://fosslight.org/fosslight-guide/scanner/

    πŸ”§ Modes
    ────────────────────────────────────────────────────────────────────
    all (default)          Run all modes (Source, Dependency, Binary)
    source                 Run FOSSLight Source analysis only
    dependency             Run FOSSLight Dependency analysis only
    binary                 Run FOSSLight Binary analysis only
    compare                Compare two FOSSLight reports

    Note: Multiple modes can be specified separated by comma
          Example: fosslight source,binary -p /path/to/analyze

    βš™οΈ  General Options
    ────────────────────────────────────────────────────────────────────
    -p <path>              Path to analyze
                           β€’ Compare mode: path to two FOSSLight reports (excel/yaml)
    -w <url>               URL to download and analyze (git clone or wget)
    -f <format>            Output format (excel, csv, opossum, yaml, spdx-yaml, spdx-json, spdx-xml, spdx-tag, cyclonedx-json, cyclonedx-xml)
                           β€’ Compare mode: excel, json, yaml, html
                           β€’ Multiple formats: ex) -f excel yaml json (separated by space)
    -e <pattern>           Exclude paths from analysis (files and directories)
                           ⚠️  IMPORTANT: Always wrap in quotes to avoid shell expansion
                           Example: fosslight -e "test/" "*.jar"
    -o <path>              Output directory or file name
    -c <number>            Number of processes for source analysis
    -r                     Keep raw data from scanners
    -t                     Hide progress bar
    -h                     Show this help message
    -v                     Show version information
    -s <path>              Apply settings from JSON file(check format with 'setting.json' in this repository)
                           Note: CLI flags override settings file
                           Example: -f yaml -s setting.json β†’ output is .yaml
    --no_correction        Skip OSS information correction with sbom-info.yaml
                           (Correction only supports excel format)
    --correct_fpath <path> Path to sbom-info.yaml file for correction
    --ui                   Generate UI mode result file
    --recursive_dep        Recursively analyze dependencies

    πŸ” Mode-Specific Options
    ────────────────────────────────────────────────────────────────────
    For 'all' or 'binary' mode:
      -u <db_url>          Database connection string
                           Format: postgresql://username:password@host:port/database

    For 'all' or 'dependency' mode:
      -d <args>            Additional arguments for dependency analysis

    πŸ’‘ Examples
    ────────────────────────────────────────────────────────────────────
    # Scan current directory with all scanners
    fosslight

    # Scan specific path with exclusions
    fosslight -p /path/to/source -e "test/" "node_modules/" "*.pyc"

    # Generate output in specific format
    fosslight -p /path/to/source -f yaml

    # Run specific modes only
    fosslight source,dependency -p /path/to/source

    # Download and analyze from git repository
    fosslight -w https://github.com/user/repo.git -o result_dir

    # Compare two FOSSLight reports
    fosslight compare -p report_v1.xlsx report_v2.xlsx -f excel

    # Run with database connection for binary analysis
    fosslight binary -p /path/to/binary -u "postgresql://user:pass@localhost:5432/sample"
  • Ex.1 How to analyze a local path 
    fosslight -p /home/source_path
  • Ex.2 How to download a link and analyze it 
    fosslight -o test_result_wget -w "https://github.com/LGE-OSS/example.git"
  • Ex.3 How to compare FOSSLight Report SBOM results to check changes/additions/deletions 
    fosslight compare -p FOSSLight_before_proj.yaml FOSSLight_after_proj.yaml -o test_result

How to call execution parameters as json

  1. Write and save execution parameter values as a JSON file in setting.json format.
  2. When executing, call the created setting.json with -s. 
    fosslight -s setting.json

    πŸ›ˆ The value called during execution takes precedence over the parameters written in the json file.
    ex. When called with β€˜-f yaml -s setting.json', the output is in yaml format.

Results

Open Source Analysis Results (all mode)

test_result/
β”œβ”€β”€ fosslight_log
β”‚   └── fosslight_log_all_260204_0925.txt
β”œβ”€β”€ fosslight_report_all_260204_0925.xlsx
└── fosslight_raw_data (with -r option)
    β”œβ”€β”€ fosslight_report_dep_260204_0925.xlsx
    β”œβ”€β”€ fosslight_report_src_260204_0925.xlsx
    └── fosslight_report_bin_260204_0925.xlsx
  • fosslight_report_all_(datetime).xlsx : FOSSLight Report format file containing Source analysis, Binary analysis, and Dependency analysis results
  • fosslight_raw_data directory: Folder where analysis result Raw Data files are created (with -r option)
    • fosslight_report_dep_(datetime).xlsx : Dependency analysis result file
    • fosslight_report_src_(datetime).xlsx : Source analysis result file
    • fosslight_report_bin_(datetime).xlsx : Binary analysis result file

fosslight_report_all_(datetime).xlsx

  • Scanner Info sheet
    This sheet displays information about the executed scanners and execution environment.
    • Tool information : Shows the name and version of the executed scanner.
    • Start time : Displays the start time of scanner execution.
    • Python version : Shows the Python version used to run the scanner.
    • Analyzed path : Displays the analyzed path (analysis path entered via β€˜-p' option or default path where the scanner was executed)
    • Excluded path : Shows paths excluded during analysis (paths entered via β€˜-e' option)
    • Comment : Displays analysis results for each scanner.
      • fosslight_dependency
        • When package manager manifest file does not exist
          Ex) [fosslight_dependency v4.1.31] No Package manager detected.
        • When package manager analysis succeeds
          -[Success] {package manager}: {project path}: {manifest file}
            Ex) [fosslight_dependency v4.1.31] Dependency Analysis Summary
      - [Success]  pypi:
      /home/worker/sample_code/example: requirements.txt
        • When package manager analysis fails
          -[Fail] {package manager}: {project path}: {manifest file} If analysis fails, see fosslight_log*.txt and the prerequisite guide: https://fosslight.org/fosslight-guide-en/scanner/1_dependency.html#-prerequisite
              Ex) [fosslight_dependency v4.1.31] Dependency Analysis Summary
        - [Fail]  yarn:
        /home/worker/sample_code/example: package.json
        If analysis fails, see fosslight_log*.txt and the prerequisite guide: https://fosslight.org/fosslight-guide-en/scanner/1_dependency.html#-prerequisite
      • fosslight_source
        • Scanned files : Total number of analyzed files
        • Detected source : Number of files where open source was detected.
          • If no open source is detected, it is displayed as β€˜Detected source: 0'.
        • KB Enable/KB Unreachable : Indicates whether KB DB is enabled.
        • Mode : Mode used for Source analysis.
      • fosslight_binary
        • Detected binaries: Number of binaries where open source was found.
        • Scanned Files : Total number of analyzed files.
  • DEP_FL_Dependency, SRC_FL_Source, BIN_FL_Binary sheet
    You can identify which scanner was executed from the sheet name and review the results for each scanner in that sheet.
    • Rows with Exclude column checked
      • test(s), doc(s), hidden files or folders are checked as Exclude.
      • When sbom-info.yaml is loaded, the loaded data is appended and analysis results for duplicate files are checked as Exclude.
    • Comment column
      • Add/Loaded by ** : Row loaded from **
      • Excluded by ** : Row excluded due to **

compare mode results

test_result/
β”œβ”€β”€ fosslight_log
β”‚   └── fosslight_log_all_260205_1101.txt
└── fosslight_compare_260205_1101.xlsx
  • fosslight_compare_(datetime).xlsx : File containing comparison results of two SBOMs in add/delete/change table format


Installation and Execution using Docker

⚠️ In Docker environment, only FOSSLight Source/Binary Scanner runs, and FOSSLight Dependency Scanner is not supported.

  1. Download FOSSLight Scanner Docker image

    Option 1. Download fosslight_scanner from Dockerhub

     $ docker pull fosslight/fosslight_scanner

    Option 2. Build image using Dockerfile (If your OS is not supported in option 1)

     $ docker build -t fosslight_scanner .

  2. Run with the built image.
    ex. Output path: /Users/git/temp/output, Analysis path: /Users/git/temp/dir_to_analyze

    $ docker run -it -v /Users/git/temp/dir_to_analyze:/app/dir_to_analyze -v /Users/git/temp/output:/app/output fosslight_scanner -p dir_to_analyze -o output