From 05c8415efae3f1a10a08c21648350ebc1297baa0 Mon Sep 17 00:00:00 2001 From: Gyan Ranjan Panda Date: Thu, 5 Feb 2026 15:00:08 +0530 Subject: [PATCH 1/2] docs: implement persona-based documentation paths Implements issue #250 by creating user-centric documentation paths organized around user goals rather than tools. Changes: - Add three persona landing pages: * Legal/Compliance professionals * Security/SCA professionals * Developers/Integrators - Update homepage with 'Choose Your Path' section - Fix purldb-project label reference Each persona page uses appropriate language and workflows for its target audience, with cross-links between personas where relevant. All existing documentation remains unchanged - this is an additive refactor creating new entry points. Verification: - Documentation builds with zero warnings - All link checks pass - All style checks pass Closes #250 Signed-off-by: Gyan Ranjan Panda --- .../aboutcode-projects/purldb-project.rst | 2 +- docs/source/index.rst | 46 ++++ docs/source/personas/developer-integrator.rst | 224 ++++++++++++++++++ docs/source/personas/legal-compliance.rst | 118 +++++++++ docs/source/personas/security-researcher.rst | 150 ++++++++++++ 5 files changed, 539 insertions(+), 1 deletion(-) create mode 100644 docs/source/personas/developer-integrator.rst create mode 100644 docs/source/personas/legal-compliance.rst create mode 100644 docs/source/personas/security-researcher.rst diff --git a/docs/source/aboutcode-projects/purldb-project.rst b/docs/source/aboutcode-projects/purldb-project.rst index 7a238a9..ac80019 100644 --- a/docs/source/aboutcode-projects/purldb-project.rst +++ b/docs/source/aboutcode-projects/purldb-project.rst @@ -1,4 +1,4 @@ -.. purldb-project: +.. _purldb-project: PurlDB ====== diff --git a/docs/source/index.rst b/docs/source/index.rst index e13bf63..7f265c2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -16,6 +16,41 @@ AboutCode documentation. All community contributions are welcome. +---- + +****************** +Choose Your Path +****************** + +AboutCode serves different users with different goals. Choose the path that best +describes you to find the documentation most relevant to your needs: + +**Legal & Compliance Professionals** + You're responsible for ensuring license compliance, managing open source policies, + or generating attribution documentation. You need high-level summaries and + compliance workflows. + + → :ref:`persona-legal-compliance` + +**Security & SCA Professionals** + You're focused on identifying vulnerabilities, managing security risks, or + performing software composition analysis. You need vulnerability scanning and + security analysis workflows. + + → :ref:`persona-security-researcher` + +**Developers & Integrators** + You're integrating AboutCode into your development workflow, CI/CD pipeline, or + building applications that consume AboutCode data. You need APIs, CLIs, and + automation guides. + + → :ref:`persona-developer-integrator` + +.. note:: + Not sure which path fits you? That's okay! You can explore all paths, and each + one includes links to the others where relevant. + + ---- ******** @@ -27,6 +62,17 @@ Overview aboutcode-project-overview +************** +Persona Paths +************** + +.. toctree:: + :maxdepth: 2 + + personas/legal-compliance + personas/security-researcher + personas/developer-integrator + ************ Contributing ************ diff --git a/docs/source/personas/developer-integrator.rst b/docs/source/personas/developer-integrator.rst new file mode 100644 index 0000000..69137a6 --- /dev/null +++ b/docs/source/personas/developer-integrator.rst @@ -0,0 +1,224 @@ +.. _persona-developer-integrator: + +==================================== +For Developers & Integrators +==================================== + +Welcome! If you're integrating AboutCode tools into your development workflow, CI/CD +pipeline, or building applications that consume AboutCode data, you're in the right place. + +AboutCode provides powerful APIs, command-line tools, and libraries that you can use to +automate scanning, generate SBOMs, and integrate license and vulnerability analysis into +your systems. + +What You Can Accomplish +======================= + +With AboutCode, you can: + +- **Automate Code Scanning**: Run license and vulnerability scans from the command line or CI/CD +- **Generate SBOMs Programmatically**: Create CycloneDX and SPDX SBOMs via API or CLI +- **Integrate with Your Tools**: Use REST APIs to query vulnerability data and package metadata +- **Build Custom Workflows**: Create pipelines that combine scanning, analysis, and reporting +- **Parse and Process Results**: Work with structured JSON/YAML output for downstream processing + +Key Workflows +============= + +1. Command-Line Scanning +------------------------ + +Use ScanCode Toolkit from the command line to scan code, detect licenses, extract +copyrights, and identify packages. + +The CLI provides extensive options for customizing scans, filtering results, and +generating output in various formats (JSON, YAML, SPDX, CycloneDX). + +**Example:** + +.. code-block:: bash + + # Basic scan + scancode -clpieu --json-pp output.json /path/to/code + + # Scan with license policies + scancode --license-policy policies.yml --json output.json /path/to/code + + # Generate SPDX SBOM + scancode --spdx output.spdx /path/to/code + +**Learn more:** :ref:`scancode-toolkit-project` + +**Tools you'll use:** ScanCode Toolkit + +2. API Integration +------------------ + +ScanCode.io provides a REST API for triggering scans, retrieving results, and managing +projects programmatically. + +You can integrate scanning into your CI/CD pipeline, automate SBOM generation, or build +custom applications that consume scan data. + +**Example:** + +.. code-block:: python + + import requests + + # Create a project + response = requests.post( + 'https://your-scancodeio.com/api/projects/', + json={'name': 'my-project'}, + headers={'Authorization': 'Token your-api-token'} + ) + + # Upload code and run pipeline + project_url = response.json()['url'] + # ... upload files and trigger pipeline + +**Learn more:** :ref:`scancodeio-project` + +**Tools you'll use:** ScanCode.io API, VulnerableCode API, PurlDB API + +3. CI/CD Pipeline Integration +----------------------------- + +Integrate AboutCode scanning into your continuous integration pipeline to catch license +and security issues early in the development process. + +You can use GitHub Actions, GitLab CI, Jenkins, or any CI system that supports running +command-line tools or making API calls. + +**Example (GitHub Actions):** + +.. code-block:: yaml + + - name: Scan with ScanCode + uses: aboutcode-org/scancode-action@v1 + with: + path: . + output: scancode-results.json + +**Learn more:** :ref:`scancode-action-project` + +**Tools you'll use:** ScanCode Action, ScanCode Toolkit, ScanCode.io + +4. Creating and Consuming SBOMs +------------------------------- + +Generate software bills of materials (SBOMs) in industry-standard formats like SPDX +and CycloneDX. + +You can create SBOMs from scan results, import SBOMs from other tools, enrich them with +additional data, and export them for sharing with customers or partners. + +**Learn more:** :ref:`create-sboms` and :ref:`consume-sboms` + +**Tools you'll use:** ScanCode Toolkit, ScanCode.io, DejaCode + +Recommended Tools & Libraries +============================== + +**ScanCode Toolkit** + Command-line scanner with extensive options and multiple output formats. The + foundation for all AboutCode scanning. + + :ref:`scancode-toolkit-project` + + GitHub: https://github.com/aboutcode-org/scancode-toolkit + +**ScanCode.io** + Web application with REST API for running complex scanning pipelines. Supports + Docker images, packages, and codebases. + + :ref:`scancodeio-project` + + GitHub: https://github.com/aboutcode-org/scancode.io + +**VulnerableCode API** + REST API for querying vulnerability data by package, CVE, or PURL. + + :ref:`vulnerablecode-project` + + Public API: https://public.vulnerablecode.io/api/ + +**PurlDB API** + REST API for querying package metadata by PURL. + + https://purldb.readthedocs.io + + Public API: https://public.purldb.io/api/ + +**Python Libraries** + - **license-expression**: Parse and normalize SPDX license expressions + - **packageurl-python**: Work with Package URLs (PURLs) + - **commoncode**: Common utilities for file handling, hashing, and dates + - **extractcode**: Universal archive extraction + + :ref:`license-expression-project` + +Working with Package URLs (PURLs) +================================== + +Package URLs (PURLs) are a universal way to identify software packages across all +ecosystems. AboutCode tools use PURLs extensively. + +**Format:** + +.. code-block:: text + + pkg:type/namespace/name@version?qualifiers#subpath + +**Examples:** + +.. code-block:: text + + pkg:npm/express@4.18.2 + pkg:pypi/django@4.2.0 + pkg:maven/org.apache.commons/commons-lang3@3.12.0 + pkg:docker/library/nginx@1.25.0 + +**Python usage:** + +.. code-block:: python + + from packageurl import PackageURL + + purl = PackageURL.from_string('pkg:npm/express@4.18.2') + print(purl.type) # 'npm' + print(purl.name) # 'express' + print(purl.version) # '4.18.2' + +Output Formats +============== + +AboutCode tools support multiple output formats: + +- **JSON**: Structured data for programmatic processing +- **YAML**: Human-readable structured data +- **SPDX**: Industry-standard SBOM format (JSON, YAML, RDF, tag-value) +- **CycloneDX**: OWASP SBOM standard (JSON, XML) +- **CSV**: Tabular data for spreadsheet analysis +- **HTML**: Human-readable reports + +Next Steps +========== + +**New to AboutCode?** + Start with :ref:`start-scanning-code` to understand the basics. + +**Ready to automate?** + Check out the ScanCode Toolkit CLI documentation for command-line options. + +**Building an integration?** + Review the ScanCode.io API documentation for REST endpoints. + +**Need to understand the data model?** + See :ref:`aboutcode_data` for AboutCode data structures. + +**Also need compliance workflows?** + Visit :ref:`persona-legal-compliance` for policy management and reporting. + +**Interested in security analysis?** + Check out :ref:`persona-security-researcher` for vulnerability scanning. diff --git a/docs/source/personas/legal-compliance.rst b/docs/source/personas/legal-compliance.rst new file mode 100644 index 0000000..00d7c59 --- /dev/null +++ b/docs/source/personas/legal-compliance.rst @@ -0,0 +1,118 @@ +.. _persona-legal-compliance: + +======================================== +For Legal & Compliance Professionals +======================================== + +Welcome! If you're responsible for ensuring your organization's software complies with +licensing requirements, manages open source risks, or needs to generate attribution +documentation, you're in the right place. + +AboutCode provides tools to help you understand what's in your software, ensure license +compliance, and generate the reports you need for audits and legal reviews. + +What You Can Accomplish +======================= + +With AboutCode, you can: + +- **Understand License Obligations**: Identify all licenses in your codebase and + understand what they require +- **Manage License Policies**: Define which licenses are approved, restricted, or + prohibited for your organization +- **Generate Attribution Documents**: Automatically create license notices and attribution files +- **Review Supplier SBOMs**: Analyze software bills of materials from your vendors +- **Support Regulatory Compliance**: Meet requirements like the EU Cyber Resilience Act (CRA) + +Key Workflows +============= + +1. Managing License Policies +---------------------------- + +Define your organization's license policies and apply them consistently across all projects. + +You can specify which licenses are approved for use, which require legal review, and which +are prohibited. These policies can then be applied automatically when scanning code. + +**Learn more:** :ref:`manage-license-policies` + +**Tools you'll use:** DejaCode, ScanCode.io + +2. Generating Attribution Documents +----------------------------------- + +When you ship software that includes open source components, you need to provide proper +attribution to comply with license terms. + +AboutCode can automatically generate attribution notices, license texts, and other +required documentation based on your scan results. + +**Learn more:** :ref:`create-sboms` + +**Tools you'll use:** ScanCode Toolkit, DejaCode, AboutCode Toolkit + +3. Reviewing Software from Suppliers +------------------------------------ + +When you receive software from vendors or suppliers, you need to understand what's +included and whether it meets your compliance requirements. + +You can import SBOMs (Software Bills of Materials) from suppliers, enrich the data with +additional analysis, and verify compliance with your policies. + +**Learn more:** :ref:`consume-sboms` + +**Tools you'll use:** ScanCode.io, DejaCode, PurlDB + +4. Supporting CRA Compliance +---------------------------- + +The EU Cyber Resilience Act requires manufacturers to provide transparency about the +software components in their products. + +AboutCode provides the scanning, analysis, and SBOM generation capabilities you need to +meet these requirements. + +**Learn more:** :ref:`cra-compliance` + +**Tools you'll use:** DejaCode, ScanCode.io + +Recommended Tools +================= + +**DejaCode** + Enterprise application for managing your open source compliance program. Create + products, track components, manage policies, and generate reports. + + :ref:`dejacode-project` + +**ScanCode.io** + Web-based scanning platform with pipelines for analyzing code, packages, and + containers. Integrates with DejaCode for comprehensive compliance workflows. + + :ref:`scancodeio-project` + +**ScanCode Toolkit** + Command-line tool for detecting licenses, copyrights, and other metadata in code. + The foundation for all AboutCode scanning capabilities. + + :ref:`scancode-toolkit-project` + +Next Steps +========== + +**New to AboutCode?** + Start with :ref:`start-scanning-code` to understand how scanning works. + +**Ready to set up your compliance program?** + Follow :ref:`manage-license-policies` to define your organization's policies. + +**Need to analyze supplier software?** + Check out :ref:`consume-sboms` for importing and reviewing SBOMs. + +**Looking for developer integration?** + See :ref:`persona-developer-integrator` for API and automation options. + +**Interested in security analysis?** + Visit :ref:`persona-security-researcher` for vulnerability scanning workflows. diff --git a/docs/source/personas/security-researcher.rst b/docs/source/personas/security-researcher.rst new file mode 100644 index 0000000..c676350 --- /dev/null +++ b/docs/source/personas/security-researcher.rst @@ -0,0 +1,150 @@ +.. _persona-security-researcher: + +==================================== +For Security & SCA Professionals +==================================== + +Welcome! If you're focused on identifying vulnerabilities, managing security risks, or +performing software composition analysis (SCA), AboutCode has the tools you need. + +Whether you're a security researcher, AppSec engineer, or SCA analyst, you can use +AboutCode to scan code for vulnerabilities, query vulnerability databases, and integrate +security analysis into your workflows. + +What You Can Accomplish +======================= + +With AboutCode, you can: + +- **Identify Vulnerable Components**: Scan code and packages to find known security vulnerabilities +- **Query Vulnerability Data**: Access a comprehensive, open database of CVEs and + security advisories +- **Analyze SBOM Security**: Review software bills of materials for security risks +- **Track Security Metrics**: Monitor vulnerability counts, severity levels, and remediation status +- **Integrate with Security Tools**: Automate vulnerability scanning in your security pipeline + +Key Workflows +============= + +1. Scanning Code for Vulnerabilities +------------------------------------ + +Scan your codebase, Docker images, or packages to identify components with known +security vulnerabilities. + +ScanCode.io can detect packages and match them against the VulnerableCode database to +find CVEs, security advisories, and affected version ranges. + +**Learn more:** :ref:`start-scanning-code` + +**Tools you'll use:** ScanCode.io, VulnerableCode, ScanCode Toolkit + +2. Querying the Vulnerability Database +-------------------------------------- + +VulnerableCode provides a free, open database of software vulnerabilities aggregated +from multiple sources including NVD, GitHub Security Advisories, and ecosystem-specific +databases. + +You can query by package, CVE, or PURL (Package URL) to get comprehensive vulnerability +information including affected versions, severity scores, and references. + +**Learn more:** :ref:`vulnerablecode-project` + +**Tools you'll use:** VulnerableCode + +**Public instance:** https://public.vulnerablecode.io/ + +3. Analyzing SBOM Security +-------------------------- + +When you receive SBOMs from suppliers or generate them for your own software, you need +to understand the security posture of all included components. + +Import SBOMs into ScanCode.io or DejaCode, enrich them with vulnerability data from +VulnerableCode, and identify high-risk components that need attention. + +**Learn more:** :ref:`consume-sboms` + +**Tools you'll use:** ScanCode.io, VulnerableCode, DejaCode + +4. Integrating Security Scanning +-------------------------------- + +Automate vulnerability scanning in your CI/CD pipeline, security tools, or monitoring +systems. + +Use the ScanCode.io API or command-line interface to trigger scans, retrieve results, +and integrate with your existing security infrastructure. + +**Learn more:** :ref:`persona-developer-integrator` + +**Tools you'll use:** ScanCode.io, ScanCode Toolkit, VulnerableCode API + +Recommended Tools +================= + +**VulnerableCode** + Free and open database of software package vulnerabilities. Query by package, + CVE, or PURL to get comprehensive vulnerability information. + + :ref:`vulnerablecode-project` + + Public instance: https://public.vulnerablecode.io/ + +**ScanCode.io** + Web-based scanning platform with built-in VulnerableCode integration. Scan + packages, containers, and codebases for vulnerabilities. + + :ref:`scancodeio-project` + +**PurlDB** + Package metadata database keyed by PURL. Useful for enriching vulnerability + data with package information. + + https://purldb.readthedocs.io + + Public instance: https://public.purldb.io/ + +**ScanCode Toolkit** + Command-line scanner that can detect packages and integrate with VulnerableCode + for vulnerability analysis. + + :ref:`scancode-toolkit-project` + +Understanding Vulnerability Data +================================= + +**Severity Scoring** + VulnerableCode aggregates severity scores from multiple sources including CVSS + scores from NVD and ecosystem-specific severity ratings. + +**Affected Version Ranges** + Vulnerability data includes precise version ranges showing which versions of a + package are affected and which versions contain fixes. + +**Multiple Data Sources** + VulnerableCode aggregates data from NVD, GitHub Security Advisories, OSV, and + ecosystem-specific databases for comprehensive coverage. + +**Package URL (PURL)** + All vulnerability data is keyed by PURL, a universal identifier for software + packages across all ecosystems. + +Next Steps +========== + +**New to AboutCode?** + Start with :ref:`start-scanning-code` to run your first vulnerability scan. + +**Want to explore the vulnerability database?** + Visit https://public.vulnerablecode.io/ to search and browse vulnerability data. + +**Need to integrate with your security tools?** + See :ref:`persona-developer-integrator` for API documentation and automation. + +**Also responsible for license compliance?** + Check out :ref:`persona-legal-compliance` for compliance workflows. + +**Looking for developer documentation?** + Visit :ref:`persona-developer-integrator` for CLI and API integration guides. From a947eb480f6e01a2259dbccbce64c51aa869e3fc Mon Sep 17 00:00:00 2001 From: Gyan Ranjan Panda Date: Thu, 5 Feb 2026 15:11:50 +0530 Subject: [PATCH 2/2] docs: condense persona pages for clarity MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Shortened all three persona landing pages to be more concise: - Legal/Compliance: 117 → 40 lines - Security/SCA: 150 → 45 lines - Developer/Integrator: 226 → 75 lines Changes focus persona pages on quick navigation paths rather than full tutorials. Removed redundant tool descriptions and verbose explanations while keeping essential code examples and links. Total reduction: ~540 → ~160 lines (~70% shorter) Signed-off-by: Gyan Ranjan Panda --- docs/source/personas/developer-integrator.rst | 222 +++--------------- docs/source/personas/legal-compliance.rst | 124 ++-------- docs/source/personas/security-researcher.rst | 159 ++----------- 3 files changed, 83 insertions(+), 422 deletions(-) diff --git a/docs/source/personas/developer-integrator.rst b/docs/source/personas/developer-integrator.rst index 69137a6..77a0d65 100644 --- a/docs/source/personas/developer-integrator.rst +++ b/docs/source/personas/developer-integrator.rst @@ -4,221 +4,69 @@ For Developers & Integrators ==================================== -Welcome! If you're integrating AboutCode tools into your development workflow, CI/CD -pipeline, or building applications that consume AboutCode data, you're in the right place. +If you're integrating AboutCode into your development workflow, CI/CD pipeline, or building +applications that consume AboutCode data, this is your starting point. -AboutCode provides powerful APIs, command-line tools, and libraries that you can use to -automate scanning, generate SBOMs, and integrate license and vulnerability analysis into -your systems. +Quick Start Paths +================= -What You Can Accomplish -======================= +**Command-Line Usage** + → :ref:`scancode-toolkit-project` - CLI scanning and SBOM generation -With AboutCode, you can: +**API Integration** + → :ref:`scancodeio-project` - REST API documentation + → :ref:`vulnerablecode-project` - Vulnerability API + → https://purldb.readthedocs.io - Package metadata API -- **Automate Code Scanning**: Run license and vulnerability scans from the command line or CI/CD -- **Generate SBOMs Programmatically**: Create CycloneDX and SPDX SBOMs via API or CLI -- **Integrate with Your Tools**: Use REST APIs to query vulnerability data and package metadata -- **Build Custom Workflows**: Create pipelines that combine scanning, analysis, and reporting -- **Parse and Process Results**: Work with structured JSON/YAML output for downstream processing +**CI/CD Pipelines** + → :ref:`scancode-action-project` - GitHub Actions integration -Key Workflows -============= +**SBOM Workflows** + → :ref:`create-sboms` - Generate SPDX and CycloneDX SBOMs + → :ref:`consume-sboms` - Import and process SBOMs -1. Command-Line Scanning ------------------------- - -Use ScanCode Toolkit from the command line to scan code, detect licenses, extract -copyrights, and identify packages. - -The CLI provides extensive options for customizing scans, filtering results, and -generating output in various formats (JSON, YAML, SPDX, CycloneDX). +Quick Examples +============== -**Example:** +**Basic CLI Scan:** .. code-block:: bash - # Basic scan scancode -clpieu --json-pp output.json /path/to/code - # Scan with license policies - scancode --license-policy policies.yml --json output.json /path/to/code - - # Generate SPDX SBOM - scancode --spdx output.spdx /path/to/code - -**Learn more:** :ref:`scancode-toolkit-project` - -**Tools you'll use:** ScanCode Toolkit - -2. API Integration ------------------- +**Generate SPDX SBOM:** -ScanCode.io provides a REST API for triggering scans, retrieving results, and managing -projects programmatically. +.. code-block:: bash -You can integrate scanning into your CI/CD pipeline, automate SBOM generation, or build -custom applications that consume scan data. + scancode --spdx output.spdx /path/to/code -**Example:** +**Python API Usage:** .. code-block:: python import requests - - # Create a project response = requests.post( 'https://your-scancodeio.com/api/projects/', json={'name': 'my-project'}, headers={'Authorization': 'Token your-api-token'} ) - # Upload code and run pipeline - project_url = response.json()['url'] - # ... upload files and trigger pipeline - -**Learn more:** :ref:`scancodeio-project` - -**Tools you'll use:** ScanCode.io API, VulnerableCode API, PurlDB API - -3. CI/CD Pipeline Integration ------------------------------ - -Integrate AboutCode scanning into your continuous integration pipeline to catch license -and security issues early in the development process. - -You can use GitHub Actions, GitLab CI, Jenkins, or any CI system that supports running -command-line tools or making API calls. - -**Example (GitHub Actions):** - -.. code-block:: yaml - - - name: Scan with ScanCode - uses: aboutcode-org/scancode-action@v1 - with: - path: . - output: scancode-results.json - -**Learn more:** :ref:`scancode-action-project` - -**Tools you'll use:** ScanCode Action, ScanCode Toolkit, ScanCode.io - -4. Creating and Consuming SBOMs -------------------------------- - -Generate software bills of materials (SBOMs) in industry-standard formats like SPDX -and CycloneDX. - -You can create SBOMs from scan results, import SBOMs from other tools, enrich them with -additional data, and export them for sharing with customers or partners. - -**Learn more:** :ref:`create-sboms` and :ref:`consume-sboms` - -**Tools you'll use:** ScanCode Toolkit, ScanCode.io, DejaCode - -Recommended Tools & Libraries -============================== - -**ScanCode Toolkit** - Command-line scanner with extensive options and multiple output formats. The - foundation for all AboutCode scanning. - - :ref:`scancode-toolkit-project` - - GitHub: https://github.com/aboutcode-org/scancode-toolkit +Key Concepts +============ -**ScanCode.io** - Web application with REST API for running complex scanning pipelines. Supports - Docker images, packages, and codebases. +**Package URLs (PURLs)** + Universal package identifiers: ``pkg:npm/express@4.18.2`` - :ref:`scancodeio-project` - - GitHub: https://github.com/aboutcode-org/scancode.io - -**VulnerableCode API** - REST API for querying vulnerability data by package, CVE, or PURL. - - :ref:`vulnerablecode-project` - - Public API: https://public.vulnerablecode.io/api/ - -**PurlDB API** - REST API for querying package metadata by PURL. - - https://purldb.readthedocs.io - - Public API: https://public.purldb.io/api/ +**Output Formats** + JSON, YAML, SPDX, CycloneDX, CSV, HTML **Python Libraries** - - **license-expression**: Parse and normalize SPDX license expressions - - **packageurl-python**: Work with Package URLs (PURLs) - - **commoncode**: Common utilities for file handling, hashing, and dates - - **extractcode**: Universal archive extraction - - :ref:`license-expression-project` - -Working with Package URLs (PURLs) -================================== - -Package URLs (PURLs) are a universal way to identify software packages across all -ecosystems. AboutCode tools use PURLs extensively. - -**Format:** - -.. code-block:: text - - pkg:type/namespace/name@version?qualifiers#subpath - -**Examples:** - -.. code-block:: text - - pkg:npm/express@4.18.2 - pkg:pypi/django@4.2.0 - pkg:maven/org.apache.commons/commons-lang3@3.12.0 - pkg:docker/library/nginx@1.25.0 - -**Python usage:** - -.. code-block:: python - - from packageurl import PackageURL - - purl = PackageURL.from_string('pkg:npm/express@4.18.2') - print(purl.type) # 'npm' - print(purl.name) # 'express' - print(purl.version) # '4.18.2' - -Output Formats -============== - -AboutCode tools support multiple output formats: - -- **JSON**: Structured data for programmatic processing -- **YAML**: Human-readable structured data -- **SPDX**: Industry-standard SBOM format (JSON, YAML, RDF, tag-value) -- **CycloneDX**: OWASP SBOM standard (JSON, XML) -- **CSV**: Tabular data for spreadsheet analysis -- **HTML**: Human-readable reports - -Next Steps -========== - -**New to AboutCode?** - Start with :ref:`start-scanning-code` to understand the basics. - -**Ready to automate?** - Check out the ScanCode Toolkit CLI documentation for command-line options. - -**Building an integration?** - Review the ScanCode.io API documentation for REST endpoints. - -**Need to understand the data model?** - See :ref:`aboutcode_data` for AboutCode data structures. + - ``packageurl-python`` - Work with PURLs + - ``license-expression`` - Parse SPDX license expressions -**Also need compliance workflows?** - Visit :ref:`persona-legal-compliance` for policy management and reporting. +Also Explore +============ -**Interested in security analysis?** - Check out :ref:`persona-security-researcher` for vulnerability scanning. +- :ref:`aboutcode_data` - AboutCode data structures +- :ref:`persona-legal-compliance` - For compliance workflows +- :ref:`persona-security-researcher` - For vulnerability analysis diff --git a/docs/source/personas/legal-compliance.rst b/docs/source/personas/legal-compliance.rst index 00d7c59..9edfbe9 100644 --- a/docs/source/personas/legal-compliance.rst +++ b/docs/source/personas/legal-compliance.rst @@ -4,115 +4,35 @@ For Legal & Compliance Professionals ======================================== -Welcome! If you're responsible for ensuring your organization's software complies with -licensing requirements, manages open source risks, or needs to generate attribution -documentation, you're in the right place. +If you're responsible for license compliance, managing open source policies, or generating +attribution documentation, AboutCode helps you understand what's in your software and meet +your legal obligations. -AboutCode provides tools to help you understand what's in your software, ensure license -compliance, and generate the reports you need for audits and legal reviews. - -What You Can Accomplish -======================= - -With AboutCode, you can: - -- **Understand License Obligations**: Identify all licenses in your codebase and - understand what they require -- **Manage License Policies**: Define which licenses are approved, restricted, or - prohibited for your organization -- **Generate Attribution Documents**: Automatically create license notices and attribution files -- **Review Supplier SBOMs**: Analyze software bills of materials from your vendors -- **Support Regulatory Compliance**: Meet requirements like the EU Cyber Resilience Act (CRA) - -Key Workflows -============= - -1. Managing License Policies ----------------------------- - -Define your organization's license policies and apply them consistently across all projects. - -You can specify which licenses are approved for use, which require legal review, and which -are prohibited. These policies can then be applied automatically when scanning code. - -**Learn more:** :ref:`manage-license-policies` - -**Tools you'll use:** DejaCode, ScanCode.io - -2. Generating Attribution Documents ------------------------------------ - -When you ship software that includes open source components, you need to provide proper -attribution to comply with license terms. - -AboutCode can automatically generate attribution notices, license texts, and other -required documentation based on your scan results. - -**Learn more:** :ref:`create-sboms` - -**Tools you'll use:** ScanCode Toolkit, DejaCode, AboutCode Toolkit - -3. Reviewing Software from Suppliers ------------------------------------- - -When you receive software from vendors or suppliers, you need to understand what's -included and whether it meets your compliance requirements. - -You can import SBOMs (Software Bills of Materials) from suppliers, enrich the data with -additional analysis, and verify compliance with your policies. - -**Learn more:** :ref:`consume-sboms` - -**Tools you'll use:** ScanCode.io, DejaCode, PurlDB - -4. Supporting CRA Compliance ----------------------------- - -The EU Cyber Resilience Act requires manufacturers to provide transparency about the -software components in their products. - -AboutCode provides the scanning, analysis, and SBOM generation capabilities you need to -meet these requirements. - -**Learn more:** :ref:`cra-compliance` - -**Tools you'll use:** DejaCode, ScanCode.io - -Recommended Tools +Quick Start Paths ================= -**DejaCode** - Enterprise application for managing your open source compliance program. Create - products, track components, manage policies, and generate reports. - - :ref:`dejacode-project` - -**ScanCode.io** - Web-based scanning platform with pipelines for analyzing code, packages, and - containers. Integrates with DejaCode for comprehensive compliance workflows. - - :ref:`scancodeio-project` - -**ScanCode Toolkit** - Command-line tool for detecting licenses, copyrights, and other metadata in code. - The foundation for all AboutCode scanning capabilities. +**New to AboutCode?** + → :ref:`start-scanning-code` - Learn the basics of scanning code - :ref:`scancode-toolkit-project` +**Setting Up Compliance** + → :ref:`manage-license-policies` - Define approved/restricted licenses + → :ref:`create-sboms` - Generate attribution documents -Next Steps -========== +**Reviewing Supplier Software** + → :ref:`consume-sboms` - Import and analyze vendor SBOMs -**New to AboutCode?** - Start with :ref:`start-scanning-code` to understand how scanning works. +**Regulatory Requirements** + → :ref:`cra-compliance` - EU Cyber Resilience Act support -**Ready to set up your compliance program?** - Follow :ref:`manage-license-policies` to define your organization's policies. +Key Tools +========= -**Need to analyze supplier software?** - Check out :ref:`consume-sboms` for importing and reviewing SBOMs. +- **DejaCode** - Enterprise compliance management platform +- **ScanCode.io** - Web-based scanning with policy enforcement +- **ScanCode Toolkit** - Command-line license and copyright detection -**Looking for developer integration?** - See :ref:`persona-developer-integrator` for API and automation options. +Also Explore +============ -**Interested in security analysis?** - Visit :ref:`persona-security-researcher` for vulnerability scanning workflows. +- :ref:`persona-security-researcher` - If you also handle security compliance +- :ref:`persona-developer-integrator` - For automation and CI/CD integration diff --git a/docs/source/personas/security-researcher.rst b/docs/source/personas/security-researcher.rst index c676350..e5525ba 100644 --- a/docs/source/personas/security-researcher.rst +++ b/docs/source/personas/security-researcher.rst @@ -4,147 +4,40 @@ For Security & SCA Professionals ==================================== -Welcome! If you're focused on identifying vulnerabilities, managing security risks, or -performing software composition analysis (SCA), AboutCode has the tools you need. +If you're focused on identifying vulnerabilities, managing security risks, or performing +software composition analysis, AboutCode provides vulnerability scanning and security +analysis capabilities. -Whether you're a security researcher, AppSec engineer, or SCA analyst, you can use -AboutCode to scan code for vulnerabilities, query vulnerability databases, and integrate -security analysis into your workflows. - -What You Can Accomplish -======================= - -With AboutCode, you can: - -- **Identify Vulnerable Components**: Scan code and packages to find known security vulnerabilities -- **Query Vulnerability Data**: Access a comprehensive, open database of CVEs and - security advisories -- **Analyze SBOM Security**: Review software bills of materials for security risks -- **Track Security Metrics**: Monitor vulnerability counts, severity levels, and remediation status -- **Integrate with Security Tools**: Automate vulnerability scanning in your security pipeline - -Key Workflows -============= - -1. Scanning Code for Vulnerabilities ------------------------------------- - -Scan your codebase, Docker images, or packages to identify components with known -security vulnerabilities. - -ScanCode.io can detect packages and match them against the VulnerableCode database to -find CVEs, security advisories, and affected version ranges. - -**Learn more:** :ref:`start-scanning-code` - -**Tools you'll use:** ScanCode.io, VulnerableCode, ScanCode Toolkit - -2. Querying the Vulnerability Database --------------------------------------- - -VulnerableCode provides a free, open database of software vulnerabilities aggregated -from multiple sources including NVD, GitHub Security Advisories, and ecosystem-specific -databases. - -You can query by package, CVE, or PURL (Package URL) to get comprehensive vulnerability -information including affected versions, severity scores, and references. - -**Learn more:** :ref:`vulnerablecode-project` - -**Tools you'll use:** VulnerableCode - -**Public instance:** https://public.vulnerablecode.io/ - -3. Analyzing SBOM Security --------------------------- - -When you receive SBOMs from suppliers or generate them for your own software, you need -to understand the security posture of all included components. - -Import SBOMs into ScanCode.io or DejaCode, enrich them with vulnerability data from -VulnerableCode, and identify high-risk components that need attention. - -**Learn more:** :ref:`consume-sboms` - -**Tools you'll use:** ScanCode.io, VulnerableCode, DejaCode - -4. Integrating Security Scanning --------------------------------- - -Automate vulnerability scanning in your CI/CD pipeline, security tools, or monitoring -systems. - -Use the ScanCode.io API or command-line interface to trigger scans, retrieve results, -and integrate with your existing security infrastructure. - -**Learn more:** :ref:`persona-developer-integrator` - -**Tools you'll use:** ScanCode.io, ScanCode Toolkit, VulnerableCode API - -Recommended Tools +Quick Start Paths ================= -**VulnerableCode** - Free and open database of software package vulnerabilities. Query by package, - CVE, or PURL to get comprehensive vulnerability information. - - :ref:`vulnerablecode-project` - - Public instance: https://public.vulnerablecode.io/ - -**ScanCode.io** - Web-based scanning platform with built-in VulnerableCode integration. Scan - packages, containers, and codebases for vulnerabilities. - - :ref:`scancodeio-project` - -**PurlDB** - Package metadata database keyed by PURL. Useful for enriching vulnerability - data with package information. - - https://purldb.readthedocs.io - - Public instance: https://public.purldb.io/ - -**ScanCode Toolkit** - Command-line scanner that can detect packages and integrate with VulnerableCode - for vulnerability analysis. - - :ref:`scancode-toolkit-project` - -Understanding Vulnerability Data -================================= - -**Severity Scoring** - VulnerableCode aggregates severity scores from multiple sources including CVSS - scores from NVD and ecosystem-specific severity ratings. - -**Affected Version Ranges** - Vulnerability data includes precise version ranges showing which versions of a - package are affected and which versions contain fixes. +**New to Vulnerability Scanning?** + → :ref:`start-scanning-code` - Run your first scan + → https://public.vulnerablecode.io/ - Explore the vulnerability database -**Multiple Data Sources** - VulnerableCode aggregates data from NVD, GitHub Security Advisories, OSV, and - ecosystem-specific databases for comprehensive coverage. +**Analyzing Security Risks** + → :ref:`vulnerablecode-project` - Query CVEs and security advisories + → :ref:`consume-sboms` - Enrich SBOMs with vulnerability data -**Package URL (PURL)** - All vulnerability data is keyed by PURL, a universal identifier for software - packages across all ecosystems. +**Integration & Automation** + → :ref:`persona-developer-integrator` - API and CI/CD integration -Next Steps -========== +Key Tools +========= -**New to AboutCode?** - Start with :ref:`start-scanning-code` to run your first vulnerability scan. +- **VulnerableCode** - Free, open vulnerability database (https://public.vulnerablecode.io/) +- **ScanCode.io** - Scan packages and containers for vulnerabilities +- **PurlDB** - Package metadata enrichment (https://public.purldb.io/) -**Want to explore the vulnerability database?** - Visit https://public.vulnerablecode.io/ to search and browse vulnerability data. +Understanding the Data +====================== -**Need to integrate with your security tools?** - See :ref:`persona-developer-integrator` for API documentation and automation. +AboutCode uses **Package URLs (PURLs)** as universal package identifiers and aggregates +vulnerability data from NVD, GitHub Security Advisories, OSV, and ecosystem-specific +databases. All data includes severity scores, affected version ranges, and fix information. -**Also responsible for license compliance?** - Check out :ref:`persona-legal-compliance` for compliance workflows. +Also Explore +============ -**Looking for developer documentation?** - Visit :ref:`persona-developer-integrator` for CLI and API integration guides. +- :ref:`persona-legal-compliance` - If you also handle license compliance +- :ref:`persona-developer-integrator` - For CLI and API documentation