From 0f0da0eab74b787a93bf1d06d36b811a054abee5 Mon Sep 17 00:00:00 2001 From: Kunal Singh Date: Thu, 23 Jul 2026 05:53:17 +0000 Subject: [PATCH 1/3] docs: simplify malware analysis for query-only, keyless workflow On-demand (active) malware analysis has been retired in vet; scanning is now a fast lookup against SafeDep's known malicious packages database and requires no API key. - Reframe the page around querying known malicious packages via `--malware-query` (`--malware` noted as a deprecated alias) - Drop the mandatory API key / SafeDep Cloud onboarding requirement; clarify cloud is optional (report sync, higher rate limits) - Remove the on-demand-only content: `--malware-analysis-timeout`, the async submit/wait note, and the retired `vet inspect malware` package inspection section - Make CI examples (GitLab, Jenkins) keyless and use `--malware-query` - Update FAQ performance note that referenced the removed timeout flag Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01EDuuXuxJY4kUsEijVwskr7 --- faq.mdx | 5 +- governance/cloud/malware-analysis.mdx | 146 ++++++++------------------ 2 files changed, 46 insertions(+), 105 deletions(-) diff --git a/faq.mdx b/faq.mdx index 5089e47..d3f68a8 100644 --- a/faq.mdx +++ b/faq.mdx @@ -118,9 +118,10 @@ Common causes: - If using `--malware`, adjust the timeout: + Malware detection with `--malware-query` is a fast lookup against SafeDep's + known malicious packages database and adds negligible overhead: ```bash - vet scan -D . --malware --malware-analysis-timeout 5m + vet scan -D . --malware-query ``` diff --git a/governance/cloud/malware-analysis.mdx b/governance/cloud/malware-analysis.mdx index 0717ce6..e34555f 100644 --- a/governance/cloud/malware-analysis.mdx +++ b/governance/cloud/malware-analysis.mdx @@ -1,11 +1,15 @@ --- title: Malware Analysis -description: "Detect malicious packages in your dependencies using SafeDep Cloud's advanced code analysis capabilities" +description: "Detect malicious packages in your dependencies by querying SafeDep's known malicious packages database" --- -Malware analysis is available for free with SafeDep Cloud. See [pricing](https://safedep.io/pricing) for details. +Malware analysis is available for free. No API key is required to query SafeDep's known malicious packages database. See [pricing](https://safedep.io/pricing) for SafeDep Cloud features. -Analyze open source packages for malicious code using [Vet](https://github.com/safedep/vet) with SafeDep Cloud's hosted analysis service. The service scans package artifacts from public package registries. +Check your open source dependencies against SafeDep's continuously updated database of known malicious packages using [Vet](https://github.com/safedep/vet). Vet queries SafeDep's threat intelligence service, which is populated through continuous static and dynamic analysis of packages from public registries. + + +Active (on-demand) analysis of arbitrary packages has been retired. Vet now performs a fast lookup against known malicious packages instead of submitting packages for analysis and waiting for results. + ## Supported Ecosystems @@ -34,11 +38,11 @@ Analyze open source packages for malicious code using [Vet](https://github.com/s - You must have [Vet](https://github.com/safedep/vet) version `1.9.7` or above installed. + Install the latest version of [Vet](https://github.com/safedep/vet). - - - You must be onboarded to SafeDep Cloud with a Tenant Domain and API Key. See [SafeDep Cloud Quickstart](/governance/cloud/quickstart) for onboarding instructions. + + + Querying known malicious packages works out of the box — no API key or SafeDep Cloud onboarding is needed. A SafeDep Cloud account is optional and only required for cloud features such as report sync and higher rate limits. See [SafeDep Cloud Quickstart](/governance/cloud/quickstart). @@ -46,44 +50,34 @@ Analyze open source packages for malicious code using [Vet](https://github.com/s ### Basic Malware Scanning -Enable malware analysis with the `--malware` flag: +Enable malware analysis with the `--malware-query` flag: ```bash -vet scan -D /path/to/code --malware +vet scan -D /path/to/code --malware-query ``` +Because Vet performs a lookup against known malicious packages, results are returned quickly, which works well for pull requests and CI/CD pipelines. + -`vet` waits for a timeout period for malware analysis to complete. This works well for pull requests and CI/CD pipelines where the number of changed packages is small. +The `--malware` flag is a deprecated alias for `--malware-query` and behaves identically. It will be removed in a future release. -### Timeout Configuration - -Adjust analysis timeout for different scenarios: - -```bash -# Quick scan with shorter timeout -vet scan -D . --malware --malware-analysis-timeout 5m - -# Thorough scan with longer timeout -vet scan -D . --malware --malware-analysis-timeout 15m -``` - ### Specific Manifest Scanning Scan individual package manifest files: ```bash # npm projects -vet scan -M package-lock.json --malware +vet scan -M package-lock.json --malware-query # Python projects -vet scan -M requirements.txt --malware +vet scan -M requirements.txt --malware-query # Go projects -vet scan -M go.mod --malware +vet scan -M go.mod --malware-query # Ruby projects -vet scan -M Gemfile.lock --malware +vet scan -M Gemfile.lock --malware-query ``` ### PURL-Based Scanning @@ -91,7 +85,7 @@ vet scan -M Gemfile.lock --malware Scan specific packages using Package URLs: ```bash -vet scan --purl pkg:npm/llm-oracle@1.0.2 --malware +vet scan --purl pkg:npm/llm-oracle@1.0.2 --malware-query ``` Malware analysis results for llm-oracle package @@ -101,7 +95,7 @@ vet scan --purl pkg:npm/llm-oracle@1.0.2 --malware Scan locally installed VS Code extensions: ```bash -vet scan --vsx --malware +vet scan --vsx --malware-query ``` @@ -110,7 +104,7 @@ VS Code extension scanning is supported only for local developer machines, not i ## GitHub Actions Integration -### vet-action Cloud Mode +### vet-action Enable malicious package protection in GitHub repositories using [vet-action](https://github.com/safedep/vet-action): @@ -125,17 +119,17 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - + - name: Run malware analysis uses: safedep/vet-action@v1 - with: - cloud: true - cloud-key: ${{ secrets.SAFEDEP_CLOUD_API_KEY }} - cloud-tenant: ${{ secrets.SAFEDEP_CLOUD_TENANT_DOMAIN }} env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` + +Known malicious package detection does not require an API key. SafeDep Cloud configuration (`cloud`, `cloud-key`, `cloud-tenant`) is optional and only enables cloud reporting and sync. See the [vet-action documentation](https://github.com/safedep/vet-action?tab=readme-ov-file#cloud-mode) for cloud mode. + + ### Pull Request Integration When enabled, Vet scans changed packages for malware and provides results directly in pull requests: @@ -146,44 +140,6 @@ Expand comments to view detailed package analysis results: Detailed malware analysis results in PR -## Package Inspection - -### Enable Experimental Feature - -Package inspection is currently experimental. Enable it with: - -```bash -export VET_ENABLE_PACKAGE_INSPECT_COMMAND=true -``` - -### Inspect Single Packages - -Perform detailed analysis of individual packages: - -```bash -vet inspect malware --purl pkg:npm/llm-oracle@1.0.2 -``` - - -Package analysis is performed asynchronously. Scanning usually takes a few minutes but may take longer depending on the analysis queue. - - -### Analysis Results - -On completion, Vet shows the analysis status and classification: - -Malware scan result showing package classification - -### Export Results - -Export analysis results as JSON: - -```bash -vet inspect malware \ - --purl pkg:npm/llm-oracle@1.0.2 \ - --report-json /tmp/analysis.json -``` - ## Understanding Results ### Classification Levels @@ -192,7 +148,9 @@ vet inspect malware \ - **SUSPICIOUS**: Potentially risky patterns identified - **MALICIOUS**: Confirmed malicious behavior found -### Analysis Techniques +### How Packages Are Analyzed + +SafeDep continuously analyzes packages from public registries and records the results in its known malicious packages database. Vet queries this database during a scan. The analysis behind these records combines: @@ -200,13 +158,13 @@ vet inspect malware \ - Suspicious function detection - Obfuscation identification - + - Network communication patterns - File system access patterns - Process execution analysis - + - Package metadata anomalies - Publisher reputation analysis @@ -226,13 +184,10 @@ malware-scan: stage: security image: ghcr.io/safedep/vet:latest script: - - vet scan -D . --malware --report-json malware-report.json + - vet scan -D . --malware-query --report-json malware-report.json artifacts: reports: security: malware-report.json - variables: - SAFEDEP_API_KEY: $SAFEDEP_API_KEY - SAFEDEP_TENANT_ID: $SAFEDEP_TENANT_ID ``` ### Jenkins Pipeline @@ -240,18 +195,12 @@ malware-scan: ```groovy pipeline { agent any - - environment { - SAFEDEP_API_KEY = credentials('safedep-api-key') - SAFEDEP_TENANT_ID = credentials('safedep-tenant-id') - } - + stages { stage('Malware Scan') { steps { - sh 'vet scan -D . --malware --report-json malware-results.json' + sh 'vet scan -D . --malware-query --report-json malware-results.json' archiveArtifacts artifacts: 'malware-results.json' - publishTestResults testResultsPattern: 'malware-results.json' } } } @@ -261,23 +210,17 @@ pipeline { ## Troubleshooting - - - Increase the timeout with `--malware-analysis-timeout` - - Scan smaller package sets - - Check network connectivity to SafeDep Cloud - - - - - Verify your API key has malware analysis permissions - - Check your tenant configuration - - Ensure you are using Vet v1.9.7 or later - - - Review the analysis details - Contact SafeDep support with the package details - Use exceptions management for temporary overrides + + + - Only packages already present in SafeDep's known malicious packages database are reported. Packages not yet analyzed are not flagged. + - Ensure you are using the latest version of Vet + - Check network connectivity to SafeDep Cloud + @@ -285,10 +228,7 @@ pipeline { Complete GitHub Actions integration guide - Get started with SafeDep Cloud for malware analysis - - - Learn more about experimental package inspection features + Optional cloud features such as report sync and higher rate limits Report bugs or request features for malware analysis From 8fe43e1069f6394a0f1f220258ee5e79d13c6a12 Mon Sep 17 00:00:00 2001 From: Kunal Singh Date: Thu, 23 Jul 2026 10:06:50 +0000 Subject: [PATCH 2/3] docs: address review feedback on malware analysis page - Move the no-API-key information out of the Requirements steps into a standalone note (Requirements now has the single Install Vet step) - Remove the em dash per docs style - Link Vet install to the installation section Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01EDuuXuxJY4kUsEijVwskr7 --- governance/cloud/malware-analysis.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/governance/cloud/malware-analysis.mdx b/governance/cloud/malware-analysis.mdx index e34555f..22955e3 100644 --- a/governance/cloud/malware-analysis.mdx +++ b/governance/cloud/malware-analysis.mdx @@ -38,14 +38,14 @@ Active (on-demand) analysis of arbitrary packages has been retired. Vet now perf - Install the latest version of [Vet](https://github.com/safedep/vet). - - - - Querying known malicious packages works out of the box — no API key or SafeDep Cloud onboarding is needed. A SafeDep Cloud account is optional and only required for cloud features such as report sync and higher rate limits. See [SafeDep Cloud Quickstart](/governance/cloud/quickstart). + Install the latest version of [Vet](https://github.com/safedep/vet/#installation). + +No API key is required. Querying known malicious packages works out of the box, with no SafeDep Cloud onboarding. A SafeDep Cloud account is optional and enables cloud features such as report sync and higher rate limits. See the [SafeDep Cloud Quickstart](/governance/cloud/quickstart). + + ## Repository Scanning ### Basic Malware Scanning From 184cd18269b3e770301e39c1059ddee006de8d2b Mon Sep 17 00:00:00 2001 From: Kunal Singh Date: Thu, 23 Jul 2026 10:44:56 +0000 Subject: [PATCH 3/3] docs: drop Steps component for single install requirement Requirements has a single item now, so a plain statement reads better than a one-step timeline. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01EDuuXuxJY4kUsEijVwskr7 --- governance/cloud/malware-analysis.mdx | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/governance/cloud/malware-analysis.mdx b/governance/cloud/malware-analysis.mdx index 22955e3..5c4e149 100644 --- a/governance/cloud/malware-analysis.mdx +++ b/governance/cloud/malware-analysis.mdx @@ -36,11 +36,7 @@ Active (on-demand) analysis of arbitrary packages has been retired. Vet now perf ## Requirements - - - Install the latest version of [Vet](https://github.com/safedep/vet/#installation). - - +Install the latest version of [Vet](https://github.com/safedep/vet/#installation). No API key is required. Querying known malicious packages works out of the box, with no SafeDep Cloud onboarding. A SafeDep Cloud account is optional and enables cloud features such as report sync and higher rate limits. See the [SafeDep Cloud Quickstart](/governance/cloud/quickstart).