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..5c4e149 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 @@ -32,58 +36,44 @@ Analyze open source packages for malicious code using [Vet](https://github.com/s ## Requirements - - - You must have [Vet](https://github.com/safedep/vet) version `1.9.7` or above installed. - - - - You must be onboarded to SafeDep Cloud with a Tenant Domain and API Key. See [SafeDep Cloud Quickstart](/governance/cloud/quickstart) for onboarding instructions. - - +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 -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 +81,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 +91,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 +100,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 +115,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 +136,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 +144,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 +154,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 +180,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 +191,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 +206,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 +224,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