Bazel Aspects

In Bazel, a rule defines how a target is built. An aspect is a reusable extension that Bazel can apply to that rule and its dependencies during analysis. Refer to the Bazel documentation for more information.

Endor Labs uses aspects to perform software composition analysis on your software packages and extract dependency information in a structured and repeatable manner.

Endor Labs provides built-in Bazel aspects that automatically enhance dependency resolution when scanning Bazel workspaces. You can run scans with aspects enabled so that Endor Labs can automatically discover and use the appropriate aspect rules for your project. If you have custom rules to build your software, you can create your own custom Bazel aspects and integrate them with Endor Labs.

Bazel aspect command reference

The following table lists the Bazel aspect command reference.

Supported open-source rulesets

Endor Labs supports Bazel aspects for the following open-source rulesets:

Run endorctl with Bazel aspects

Run the following command to scan the workspace using Bazel aspects.

endorctl scan --use-bazel --use-bazel-aspects

Aspect directory structure

Aspect rules are located under the .endorctl/aspects directory in the workspace.

For example, if your workspace is located at ~/my-workspace, the aspect rules will be located at ~/my-workspace/.endorctl/aspects.

Place your custom aspects in the .endorctl/aspects/custom directory.

How Bazel aspect scans work

When Endor Labs scans a Bazel workspace with aspects enabled, it performs the following steps:

1. Set up Aspects: Initializes and extracts the Bazel aspects plugin to the workspace.
2. Query the workspace: Runs bazel query to get information about the rules versions used in the workspace.
3. Query the target: Runs bazel query to query the target being scanned and get information about the external dependencies used by it.
4. Execute the aspect rule: Runs bazel build to execute the aspect rule.
5. Read the aspect output: Reads the aspect output to get the dependency information.

Bazel aspect output

Bazel aspects output data in JSON format, which Endor Labs uses to populate the dependency graph.

Bazel build configuration

When executing aspects, Endor Labs runs bazel build with specific flags and configuration.

Bazel aspect configuration flags

Endor Labs creates a temporary .bazelrc configuration that includes:

Bazel aspect remote execution and caching

When using remote executors or remote caching, aspect-generated files may be stored remotely, making them inaccessible to endorctl for processing.

To ensure all Bazel aspect outputs are available locally, endorctl automatically sets the following flags:

• --remote_download_outputs=all: Forces all aspect outputs to be downloaded locally when using remote executors (for example, Build without Bytes). This is required because endorctl needs to read the json files generated by aspects to populate the dependency graph.
• --remote_download_toplevel_outputs=all: Ensures top-level outputs are also downloaded locally, which is necessary for accessing aspect-generated files.

For more information about these Bazel flags, refer to the Bazel command-line reference.

Custom Bazel aspects

You can extend Bazel with custom rules to support proprietary toolchains, internal build workflows or enterprise-specific requirements that are not covered by Bazel’s built-in rules. While powerful, these custom rules can obscure dependency information from standard analysis tools.

Dependency information in custom aspects

Endor Labs can automatically analyze dependencies for open-source rule sets. However, custom rules often define dependencies in a non-standard way, such as:

• Generated targets
• Internal dependency resolution logic

Since Bazel considers custom rules as first-class citizens, dependency information inside them is not automatically visible unless explicitly surfaced. Without an aspect, Endor Labs cannot reliably determine:

• What dependencies the rule introduces
• Whether those dependencies are internal or third-party
• How they relate to the rest of the build graph

Custom aspects solve this by explicitly exposing dependency metadata in a format Endor Labs understands.

Prerequisites for building custom aspects

Before you can get started with developing your own aspects, ensure you have the following set up.

Repository Access

Your machine must have the relevant permissions to access the git repository regardless of where it is hosted, be it GitHub, GitLab, or self-hosted.

Bazel

Bazel should be installed in the machine you are going to build custom aspects. If you don’t have it installed already, follow the Bazel installation instructions.

Run the following command to check your Bazel installation.

bazel version

endorctl CLI

You also need the endorctl CLI available in your path. See endorctl CLI documentation for more information.

Build your custom Bazel aspects

The following sections provide information to help you build your custom Bazel aspects.

• Determine if a custom aspect is required
• Custom aspect directory structure
• Aspect attributes
• Output file schema definition for custom aspects
• Bazel custom aspect example

To help engineers get started, we have open-sourced an example for JavaScript rules. You can find the complete codebase in the example repository.

Determine if a custom aspect is required

You need a custom Bazel aspect if:

• Your dependency graph flows through a custom Bazel rule kind (rule class) that Endor Labs does not support out of the box, such as my_company_js_binary.
• The rule declares dependencies in non-standard locations, including custom attribute names, generated targets, or internal dependency resolution logic.

Custom aspect directory structure

Custom aspects must be available in the repository that you want to scan.

Ensure that you organize them as shown in the following directory structure for endorctl to recognize them. Use –bazel-aspect-package to configure the base package (defaults to @//.endorctl/aspects).

.endorctl/aspects/
└── custom/                           # User-defined custom aspects
   └── {ecosystem}/
       └── {rule_class}/             # Directory named after rule class
           └── {rule_class}.bzl      # Custom aspect file

Use the following path pattern to create your custom aspect.

{baseAspectPackage}/custom/{ecosystem}/{rule_class}/{rule_class}.bzl

Aspect attributes

Your custom aspect must be named endor_resolve_dependencies. endorctl discovers it by looking for this symbol in a .bzl file at the path described above.

The aspect definition must declare attr_aspects to tell Bazel which rule attributes to traverse (for example, deps, data, srcs). It must also declare the following mandatory attributes. The scan fails if any are excluded.

The following attribute is language-specific and optional.

Output file schema definition for custom aspects

The output files must be JSON. Serialize your provider (for example, EndorDependencyInfo) to JSON with json.encode_indent(). The following table lists the fields Endor Labs expects.

Bazel custom aspect example

The Endor Labs aspects example repository provides a complete custom aspect for JavaScript rules.

The example defines an EndorDependencyInfo provider that carries the metadata Endor Labs needs for each target: original_label, purl, dependencies, internal, vendored, and hide.

After defining the provider, it defines helper functions. _get_dependency_list() goes through each dependency attribute, and collects labels of targets that have an endor_sca_info output group. _get_dependency_files() collects the output files from those targets. _get_sca_information() resolves the package name and version from the rule context, and falls back to the target label and ref attribute when explicit metadata is not available.

The aspect implementation (_impl) extracts deps, data, src, and srcs from the rule attributes. It calls the helpers to build a list of dependency labels and collect transitive dependency files. It then constructs a PURL (for example, pkg:npm/package-name@version), populates the EndorDependencyInfo provider, and writes it to a JSON file using json.encode_indent(). Finally, it returns OutputGroupInfo(endor_sca_info = depset([output_file] + dependency_files)), combining the current target’s output with all files from its transitive dependencies.

The aspect itself is defined as endor_resolve_dependencies with the mandatory attributes described in Aspect attributes.

endorctl reads the resulting depsets through the Build Event Protocol (BEP) to construct the complete dependency graph. These files must be available locally. endorctl ensures downloads when using remote execution or caching (see Bazel aspect remote execution and caching).