Package: owasp-depscan
IntroductionOWASP dep-scan is a next-generation security and risk audit tool based on known vulnerabilities, advisories, and license limitations for project dependencies. Both local repositories and container images are supported as the input, and the tool is ideal for integration with ASPM/VM platforms and in CI environments.ContentsFeaturesVulnerability Data sourcesLinux distrosUsageOCI Artifacts via ORAS cliSingle binary executablesServer modeScanning projects locally (Python version)Scanning containers locally (Python version)Scanning projects locally (Docker container)Supported languages and package formatReachability analysisExample analysis for a Java projectExample analysis for a JavaScript projectCustomization through environment variablesGitHub Security AdvisorySuggest modePackage Risk auditAutomatic adjustmentConfiguring weightsLive OS scanLicense scanKubernetes and Cloud appsPDF reportsCustom reportsPerformance tuningUse nydus to speed up the initial vdb downloadDiscord supportLicenseFeaturesScan most application code - local repos, Linux container images, Kubernetes manifests, and OS - to identify known CVEs with prioritizationPerform advanced reachability analysis for multiple languages (See reachability analysis)Package vulnerability scanning is performed locally and is quite fast. No server is used!Generate Software Bill-of-Materials (SBOM) with Vulnerability Disclosure Report (VDR) informationGenerate a Common Security Advisory Framework (CSAF) 2.0 VEX document (check out theCSAF Readme)Perform deep packages risk audit for dependency confusion attacks and maintenance risks (See risk audit)Vulnerability Data sourcesOSVNVDGitHubNPMLinuxvuln-listLinux distrosAlmaLinuxDebianAlpineAmazon LinuxArch LinuxRHEL/CentOSRocky LinuxUbuntuOpenSUSE/SLESPhotonChainguardWolfi OSApplication vulnerabilities would be reported for all Linux distros and Windows. To download the full vulnerability database suitable for scanning OS, invoke dep-scan with--cachefor the first time. dep-scan would also download the appropriate database based on project type automatically.Usagedep-scan is ideal for use during continuous integration (CI) and as a local development tool.OCI Artifacts via ORAS cliUseORAS clito download the vulnerability database for effortless integration. Example workflow ishere.exportVDB_HOME=depscan
mkdir-p$VDB_HOMEoraspullghcr.io/appthreat/vdb:v5-o$VDB_HOME# oras pull ghcr.io/appthreat/vdb-10y:v5 -o $VDB_HOMEoraspullghcr.io/owasp-dep-scan/depscan:v4-o$VDB_HOMEUsevdb-10ywhich is a larger database with vulnerability data spanning the last 10 years from 2014. In contrast, vdb with a starting year of 2018 is appropriate for most users.Single binary executablesDownload the executable binary for your operating system from thereleases page. These binary bundle the following:dep-scan with Python 3.11cdxgen with Node.js 21cdxgen binary pluginscurl-LOhttps://github.com/owasp-dep-scan/depscan-bin/releases/latest/download/depscan-linux-amd64
chmod+xdepscan-linux-amd64
./depscan-linux-amd64--helpOn Windows,curl-LOhttps://github.com/owasp-dep-scan/depscan-bin/releases/latest/download/depscan.exe.\depscan.exe--helpServer modedep-scan and cdxgen could be run in server mode. Use the included docker-compose file to get started.gitclonehttps://github.com/owasp-dep-scan/dep-scan
dockercomposeupdepscan--server--server-host0.0.0.0--server-port7070In server mode, use/cacheendpoint to cache the vulnerability database.# This would take over 5 minutescurlhttp://0.0.0.0:7070/cacheUse the/scanendpoint to perform scans.[!NOTE]
Thetypeparameter is mandatory in server mode.Scanning a local directory.curl--json'{"path": "/tmp/vulnerable-aws-koa-app", "type": "js"}'http://0.0.0.0:7070/scanScanning a SBOM file (present locally).curl--json'{"path": "/tmp/vulnerable-aws-koa-app/sbom_file.json", "type": "js"}'http://0.0.0.0:7070/scanScanning a GitHub repo.curl--json'{"url": "https://github.com/HooliCorp/vulnerable-aws-koa-app", "type": "js"}'http://0.0.0.0:7070/scan-oapp.vdr.jsonUploading a SBOM file and generating results based on it.curl-XPOST-H'Content-Type: multipart/form-data'-F'file=@/tmp/app/sbom_file.json'http://0.0.0.0:7070/scan?type=jsScanning projects locally (Python version)sudonpminstall-g@cyclonedx/cdxgen
pipinstallowasp-depscanThis would install two commands calledcdxgenanddepscan.You can invoke the scan command directly with the various options.cd<projecttoscan>
depscan--src$PWD--reports-dir$PWD/reportsThe full list of options is below:usage:cli.py[-h][--no-banner][--cache][--csaf][--sync][--profile{appsec,research,operational,threat-modeling,license-compliance,generic}][--no-suggest][--risk-audit][--private-nsPRIVATE_NS][-tPROJECT_TYPE][--bomBOM][-iSRC_DIR_IMAGE][-oREPORT_FILE][--reports-dirREPORTS_DIR][--report-templateREPORT_TEMPLATE][--report-nameREPORT_NAME][--no-error][--no-license-scan][--deep][--no-universal][--no-vuln-table][--threatdb-serverTHREATDB_SERVER][--threatdb-usernameTHREATDB_USERNAME][--threatdb-passwordTHREATDB_PASSWORD][--threatdb-tokenTHREATDB_TOKEN][--server][--server-hostSERVER_HOST][--server-portSERVER_PORT][--cdxgen-serverCDXGEN_SERVER][--debug][--explain][--reachables-slices-fileREACHABLES_SLICES_FILE][-v]Fullyopen-sourcesecurityandlicenseauditforapplicationdependenciesandcontainerimagesbasedonknownvulnerabilitiesandadvisories.

options:-h,--helpshowthishelpmessageandexit--no-bannerDonotdisplaybanner--cacheCachevulnerabilityinformationinplatformspecificuser_data_dir--csafGenerateaOASISCSAFVEXdocument--syncSynctoreceivethelatestvulnerabilitydata.Shouldhaveinvokedcachefirst.--profile{appsec,research,operational,threat-modeling,license-compliance,generic}ProfiletousewhilegeneratingtheBOM.--no-suggestDisablesuggestmode--risk-auditPerformpackageriskaudit(slowoperation).Npmonly.--private-nsPRIVATE_NSPrivatenamespacetousewhileperformingossriskaudit.Privatepackagesshouldnotbeavailableinpublicregistriesbydefault.Commaseparatedvaluesaccepted.-tPROJECT_TYPE,--typePROJECT_TYPEOverrideprojecttypeifauto-detectionisincorrect--bomBOMExamineusingthegivenSoftwareBill-of-Materials(SBOM)fileinCycloneDXformat.Usecdxgencommandtoproduceone.-iSRC_DIR_IMAGE,--srcSRC_DIR_IMAGESourcedirectoryorcontainerimageorbinaryfile-oREPORT_FILE,--report_fileREPORT_FILEDEPRECATED.Usereportsdirectorysincemultiplefilesarecreated.Reportfilenamewithdirectory--reports-dirREPORTS_DIRReportsdirectory--report-templateREPORT_TEMPLATEJinjatemplatefileusedforrenderingacustomreport--report-nameREPORT_NAMEFilenameofthecustomreportwrittentothe--reports-dir--no-errorUNUSED:Continueonerrortopreventbuildfrombreaking--no-license-scanUNUSED:dep-scandoesn'tperformlicensescanningbydefault--deepPerformdeepscanbypassingthis--deepargumenttocdxgen.UsefulwhilescanningdockerimagesandOSpackages.--no-universalDepscanwouldattempttoperformasingleuniversalscaninsteadofindividualscansperlanguagetype.--no-vuln-tableDonotprintthetablewiththefulllistofvulnerabilities.Thiscanhelpreduceconsoleoutput.--threatdb-serverTHREATDB_SERVERThreatDBserverurl.Eg:https://api.sbom.cx--threatdb-usernameTHREATDB_USERNAMEThreatDBusername--threatdb-passwordTHREATDB_PASSWORDThreatDBpassword--threatdb-tokenTHREATDB_TOKENThreatDBtokenfortokenbasedsubmission--serverRundepscanasaserver--server-hostSERVER_HOSTdepscanserverhost--server-portSERVER_PORTdepscanserverport--cdxgen-serverCDXGEN_SERVERcdxgenserverurl.Eg:http://cdxgen:9090--debugRundepscanindebugmode.--explainMakesdepscantoexplainthevariousanalysis.Usefulforcreatingdetailedreports.--reachables-slices-fileREACHABLES_SLICES_FILEPathforthereachablesslicesfilecreatedbyatom.--purlSEARCH_PURLScanasinglepackageurl.-v,--versionDisplaytheversionScanning containers locally (Python version)Scanlatesttag of the containershiftleft/scan-slimdepscan--cache--srcshiftleft/scan-slim-ocontainertests/depscan-scan.json-tdockerIncludelicenseto the type to perform the license audit.depscan--cache--srcshiftleft/scan-slim-ocontainertests/depscan-scan.json-tdocker,licenseYou can also specify the image using the sha256 digestdepscan--srcredmine@sha256:a5c5f8a64a0d9a436a0a6941bc3fb156be0c89996add834fe33b66ebeed2439e-ocontainertests/depscan-redmine.json-tdockerYou can also save container images using docker or podman save command and pass the archive to depscan for scanning.dockersave-o/tmp/scanslim.tarshiftleft/scan-slim:latest# podman save --format oci-archive -o /tmp/scanslim.tar shiftleft/scan-slim:latestdepscan--src/tmp/scanslim.tar-oreports/depscan-scan.json-tdockerRefer to the docker tests under the GitHub action workflow for this repo for more examples.Scanning projects locally (Docker container)ghcr.io/owasp-dep-scan/dep-scancontainer image can be used to perform the scan.To scan with default settingsdockerrun--rm-v$PWD:/appghcr.io/owasp-dep-scan/dep-scan--src/app--reports-dir/app/reportsTo scan with custom environment variables based configurationdockerrun--rm\-eVDB_HOME=/db\-eGITHUB_TOKEN=<token>\-v/tmp:/db\-v$PWD:/appghcr.io/owasp-dep-scan/dep-scan--src/app--reports-dir/app/reportsIn the above example,/tmpis mounted as/dbinto the container. This directory is then specified asVDB_HOMEfor caching the vulnerability information. This way the database can be cached and reused to improve performance.Supported languages and package formatdep-scan usescdxgencommand internally to create a Software Bill-of-Materials (SBOM) file for the project. This is then used for performing the scans.The following projects and package-dependency format is supported by cdxgen.LanguagePackage formatnode.jspackage-lock.json, pnpm-lock.yaml, yarn.lock, rush.js, bower.json, .min.jsjavamaven (pom.xml [1]), gradle (build.gradle, .kts), scala (sbt), bazelphpcomposer.lockpythonsetup.py, requirements.txt [2], Pipfile.lock, poetry.lock, bdist_wheel, .whl, .egg-infogobinary, go.mod, go.sum, Gopkg.lockrubyGemfile.lock, gemspecrustbinary, Cargo.toml, Cargo.lock.Net.csproj, packages.config, project.assets.json [3], packages.lock.json, .nupkgdartpubspec.lock, pubspec.yamlhaskellcabal.project.freezeelixirmix.lockc/c++conan.lock, conanfile.txtclojureClojure CLI (deps.edn), Leiningen (project.clj)docker / oci imageAll supported languages and Linux OS packagesGitHub Actions Workflows.github/workflows/*.ymlJenkins Plugins.hpi filesYAML manifestsdocker-compose, kubernetes, kustomization, skaffold, tekton etcReachability analysisDepscan can perform reachability analysis for Java, JavaScript, TypeScript and Python with built-in support for parsingatomreachables slicing. Simply invoke depscan with theresearchprofile and language type to enable this feature.To receive a verbose output including the reachable flows, pass the argument--explain--profileresearch-tlanguage[--explain]Example analysis for a Java projectdepscan--profileresearch-tjava-i<sourcedirectory>--reports-dir<reportsdirectory>--explainExample analysis for a JavaScript projectdepscan--profileresearch-tjs-i<sourcedirectory>--reports-dir<reportsdirectory>--explainExample analysis for a PHP projectEnsure PHP > 7.4 is installed. However, we support scanning PHP 5.2 - 8.3. Alternatively, use the depscan container image.depscan--profileresearch-tphp-i<sourcedirectory>--reports-dir<reportsdirectory>--explainCustomization through environment variablesThe following environment variables can be used to customize the behavior.VDB_HOME - Directory to use for caching database. For docker-based execution, this directory should get mounted as a volume from the hostVDB_DATABASE_URL - Vulnerability DB URL. Defaults to: ghcr.io/appthreat/vdbgz:v5USE_VDB_10Y - Set to true to use the larger 10-year vulnerability database. Default download url: ghcr.io/appthreat/vdb-10y:v5GitHub Security AdvisoryTo download security advisories from GitHub, a personal access token with minimal permissions is necessary.Fine-grained token: Grant no permissions and select the following for repository access:Public Repositories (read-only)Token (classic): Grant no permissionsexportGITHUB_TOKEN="<PAT token>"Suggest modeDepscan comes with a suggest mode enabled by default to simplify the triaging experience. The fix version for each vulnerability is retrieved from the sources. Sometimes, there might be known vulnerabilities in the fix version reported. Eg: in the below screenshot the fix versions suggested for jackson-databind might contain known vulnerabilities.Notice, how the new suggested version is2.9.10.5which is an optimal fix version. Please note that the optimal fix version may not be the appropriate version for your application based on compatibility.Pass--no-suggestto disable this behavior.Package Risk audit--risk-auditargument enables package risk audit. Currently, only npm and PyPI packages are supported in this mode. Some risk factors are identified and assigned weights to compute a final risk score. Packages that then exceed a maximum risk score (config.pkg_max_risk_score) are presented in a table.Use--private-nsto specify the private package namespace that should be checked for dependency confusion type issues where a private package is available on the public npm/pypi registry.For example, to check if private packages with namespaces @appthreat and @shiftleft are not accidentally made public, use the below argument.--private-ns appthreat,shiftleftRisk categoryDefault WeightReasonpkg_private_on_public_registry4Private package is available on a public registrypkg_min_versions2Packages with less than 3 versions represent an extreme where they could be either super stable or quite recent. Special heuristics are applied to ignore older stable packagesmod_create_min_seconds1Less than 12 hours difference between modified and creation time. This indicates that the upload had a defect that had to be rectified immediately. Sometimes, such a rapid update could also be maliciouslatest_now_min_seconds0.5Less than 12 hours difference between the latest version and the current time. Depending on the package such a latest version may or may not be desirablelatest_now_max_seconds0.5Package versions that are over 6 years old are in use. Such packages might have vulnerable dependencies that are known or yet to be foundpkg_min_maintainers2Package has less than 2 maintainers. Many opensource projects have only 1 or 2 maintainers so special heuristics are used to ignore older stable packagespkg_min_users0.25Package has less than 2 npm userspkg_install_scripts2Package runs a custom pre or post installation scripts. This is often malicious and a downside of npm.pkg_node_version0.5Package supports outdated version of node such as 0.8, 0.10, 4 or 6.x. Such projects might have prototype pollution or closure related vulnerabilitiespkg_scope4 or 0.5Packages that are used directly in the application (required scope) gets a score with a weight of 4. Optional packages get a score of 0.25deprecated1Latest version is deprecatedRefer topkg_query.py::get_category_scoremethod for the risk formula.Automatic adjustmentA parameter calledcreated_now_quarantine_secondsis used to identify packages that are safely past the quarantine period (1 year). Certain risks such aspkg_min_versionsandpkg_min_maintainersare suppressed for packages past the quarantine period. This adjustment helps reduce noise since it is unlikely that a malicious package can exist in a registry unnoticed for over a year.Configuring weightsAll parameters can be customized by using environment variables. For eg:export PKG_MIN_VERSIONS=4 to increase and set the minimum versions category to 4.Live OS scanBy passing-t os, depscan can generate an SBOM for a live operating system or a VM with OS packages and kernel information. Optionally, pass the argument--deepto generate an SBOM with both OS and application packages and to check for application vulnerabilities.All OS packages.depscan-tos-i.-oreports/depscan.jsonAll OS and application packages.depscan-tos--deep-i.-oreports/depscan.jsonLicense scandep-scan can scan the dependencies for any license limitations and report them directly on the console log. To enable license scanning set the environment variableFETCH_LICENSEtotrue.export FETCH_LICENSE=trueThe license data is sourced from choosealicense.com and is quite limited. If the license of a given package cannot be reliably matched against this list it will get silently ignored to reduce any noise. This behavior could change in the future once the detection logic gets improved.Kubernetes and Cloud appsdep-scan could auto-detect most cloud applications and Kubernetes manifest files. Pass the argument-t yaml-manifestto manually specify the type.PDF reportsEnsurewkhtmltopdfis installed or use the official container image to generate pdf reports. Use with--explainfor more detailed reports.Custom reportsdep-scan can be provided with aJinjatemplate using the--report-templateparameter.
Giving it will pass the vulnerability report into your template for rendering the report.Please find a basic example here:{%ifmetadata-%}Report for{{metadata.component.group}}:{{metadata.component.name}}:{{metadata.component.version}}{%endif-%}{%ifvulnerabilities-%}There were{{vulnerabilities|length}}issues identified:{%forvulninvulnerabilities-%}*{{vuln['bom-ref']}}-{{vuln.recommendation}}{%endfor-%}{%else-%}🏆 _No vulnerabilities found_{%endif-%}Severity counts:* Low:{{summary.LOW}}* Medium:{{summary.MEDIUM}}* High:{{summary.HIGH}}* Critical:{{summary.CRITICAL}}* Unspecified:{{summary.UNSPECIFIED}}The objects available are taken from the CycloneDX *.vdr.json BOM file generated, just have a look at the file for its full structure:metadatavulnerabilitiescomponentsdependenciesservicessummaryis a dictionary type with vulnerability severity quantities as shown in the example above.pkg_vulnerabilities- Same asvulnerabilitiesfrom the VDRpkg_group_rows- List of vulnerability id and the dependency tree prioritized by depscan.Furthermore, insights are imaginable to be made available to the template, please reach out or contribute on demand.
We appreciate it if you like to contribute your report templates as examples, please add/find themhere.Performance tuningUse nydus to speed up the initial vdb downloadvdb v5 is published in RAFS (Registry Accelerated File System) format with better de-duplication and packing. depscan would automatically use this image ifnydus-staticbinary is available in the PATH.curl-LOhttps://github.com/dragonflyoss/nydus/releases/download/v2.2.4/nydus-static-v2.2.4-linux-amd64.tgz
tar-xvfnydus-static-v2.2.4-linux-amd64.tgz
chmod+xnydus-static/*
mvnydus-static/*/usr/local/bin/Discord supportThe developers could be reached via thediscordchannel for enterprise support.LicenseMIT LicenseThis project was donated to the OWASP Foundation in August 2023 by AppThreat Ltd.