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..77a0d65 --- /dev/null +++ b/docs/source/personas/developer-integrator.rst @@ -0,0 +1,72 @@ +.. _persona-developer-integrator: + +==================================== +For Developers & Integrators +==================================== + +If you're integrating AboutCode into your development workflow, CI/CD pipeline, or building +applications that consume AboutCode data, this is your starting point. + +Quick Start Paths +================= + +**Command-Line Usage** + → :ref:`scancode-toolkit-project` - CLI scanning and SBOM generation + +**API Integration** + → :ref:`scancodeio-project` - REST API documentation + → :ref:`vulnerablecode-project` - Vulnerability API + → https://purldb.readthedocs.io - Package metadata API + +**CI/CD Pipelines** + → :ref:`scancode-action-project` - GitHub Actions integration + +**SBOM Workflows** + → :ref:`create-sboms` - Generate SPDX and CycloneDX SBOMs + → :ref:`consume-sboms` - Import and process SBOMs + +Quick Examples +============== + +**Basic CLI Scan:** + +.. code-block:: bash + + scancode -clpieu --json-pp output.json /path/to/code + +**Generate SPDX SBOM:** + +.. code-block:: bash + + scancode --spdx output.spdx /path/to/code + +**Python API Usage:** + +.. code-block:: python + + import requests + response = requests.post( + 'https://your-scancodeio.com/api/projects/', + json={'name': 'my-project'}, + headers={'Authorization': 'Token your-api-token'} + ) + +Key Concepts +============ + +**Package URLs (PURLs)** + Universal package identifiers: ``pkg:npm/express@4.18.2`` + +**Output Formats** + JSON, YAML, SPDX, CycloneDX, CSV, HTML + +**Python Libraries** + - ``packageurl-python`` - Work with PURLs + - ``license-expression`` - Parse SPDX license expressions + +Also Explore +============ + +- :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 new file mode 100644 index 0000000..9edfbe9 --- /dev/null +++ b/docs/source/personas/legal-compliance.rst @@ -0,0 +1,38 @@ +.. _persona-legal-compliance: + +======================================== +For Legal & Compliance Professionals +======================================== + +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. + +Quick Start Paths +================= + +**New to AboutCode?** + → :ref:`start-scanning-code` - Learn the basics of scanning code + +**Setting Up Compliance** + → :ref:`manage-license-policies` - Define approved/restricted licenses + → :ref:`create-sboms` - Generate attribution documents + +**Reviewing Supplier Software** + → :ref:`consume-sboms` - Import and analyze vendor SBOMs + +**Regulatory Requirements** + → :ref:`cra-compliance` - EU Cyber Resilience Act support + +Key Tools +========= + +- **DejaCode** - Enterprise compliance management platform +- **ScanCode.io** - Web-based scanning with policy enforcement +- **ScanCode Toolkit** - Command-line license and copyright detection + +Also Explore +============ + +- :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 new file mode 100644 index 0000000..e5525ba --- /dev/null +++ b/docs/source/personas/security-researcher.rst @@ -0,0 +1,43 @@ +.. _persona-security-researcher: + +==================================== +For Security & SCA Professionals +==================================== + +If you're focused on identifying vulnerabilities, managing security risks, or performing +software composition analysis, AboutCode provides vulnerability scanning and security +analysis capabilities. + +Quick Start Paths +================= + +**New to Vulnerability Scanning?** + → :ref:`start-scanning-code` - Run your first scan + → https://public.vulnerablecode.io/ - Explore the vulnerability database + +**Analyzing Security Risks** + → :ref:`vulnerablecode-project` - Query CVEs and security advisories + → :ref:`consume-sboms` - Enrich SBOMs with vulnerability data + +**Integration & Automation** + → :ref:`persona-developer-integrator` - API and CI/CD integration + +Key Tools +========= + +- **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/) + +Understanding the Data +====================== + +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 Explore +============ + +- :ref:`persona-legal-compliance` - If you also handle license compliance +- :ref:`persona-developer-integrator` - For CLI and API documentation