diff --git a/docs/source/pages/cli_usage/action_dump_defaults.rst b/docs/source/pages/cli_usage/action_dump_defaults.rst index b439dc91f..2915573e1 100644 --- a/docs/source/pages/cli_usage/action_dump_defaults.rst +++ b/docs/source/pages/cli_usage/action_dump_defaults.rst @@ -1,6 +1,8 @@ .. Copyright (c) 2023 - 2023, Oracle and/or its affiliates. All rights reserved. .. Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/. +.. _action_dump_defaults: + ============= Dump Defaults ============= diff --git a/docs/source/pages/using.rst b/docs/source/pages/using.rst index ff05c7fa9..04a312bc0 100644 --- a/docs/source/pages/using.rst +++ b/docs/source/pages/using.rst @@ -110,6 +110,43 @@ With the example above, the generated output reports can be seen here: - `micronaut-core.html <../_static/examples/micronaut-projects/micronaut-core/analyze_with_sbom/micronaut-core.html>`__ - `micronaut-core.json <../_static/examples/micronaut-projects/micronaut-core/analyze_with_sbom/micronaut-core.json>`__ +''''''''''''''''''''''''''' +Analyzing more dependencies +''''''''''''''''''''''''''' + +In some cases the dependencies that Macaron discovers lack a direct connection to a repository for it to analyze. To improve results in these instances, the Repository Finding feature can be enabled. This feature makes use of a dependency's identifying information that can be found using the package registries located on the Internet. + +.. note:: The Repository Finding feature currently only works for Java projects via SCM meta data found within artifact POM files. + +This feature is enabled by default. To disable, or configure its behaviour in other ways, a custom ``defaults.ini`` should be passed to Macaron during execution. + +See :ref:`dump-defaults `, the CLI command to dump the default configurations in ``defaults.ini``. After making changes, see :ref:`analyze ` CLI command for the option to pass the modified ``defaults.ini`` file. + +Within the configuration file under the ``repofinder.java`` header, five options exist: ``find_repos``, ``artifact_repositories``, ``repo_pom_paths``, ``find_parents``, ``artifact_ignore_list``. These options behave as follows: + +- ``find_repos`` (Values: True or False) - Enables or disables the Repository Finding feature. +- ``artifact_repositories`` (Values: List of URLs) - Determines the remote artifact repositories to attempt to retrieve dependency information from. +- ``repo_pom_paths`` (Values: List of POM tags) - Determines where to search for repository information in the POM files. E.g. scm.url. +- ``find_parents`` (Values: True or False) - When enabled, the Repository Finding feature will also search for repository URLs in parents POM files of the current dependency. +- ``artifact_ignore_list`` (Values: List of GAs) - The Repository Finding feature will skip any artifact in this list. Format is "GroupId":"ArtifactId". E.g. org.apache.maven:maven + +.. note:: Finding repositories requires at least one remote call, adding some additional overhead to an analysis run. + +An example configuration file for utilising this feature: + +.. code-block:: ini + + [repofinder.java] + find_repos = True + artifact_repositories = https://repo.maven.apache.org/maven2 + repo_pom_paths = + scm.url + scm.connection + scm.developerConnection + find_parents = True + artifact_ignore_list = + org.apache.maven:maven + ------------------------------------- Analyzing a locally cloned repository -------------------------------------