User attribution

Package Firewall authenticates every request with one API key, so each event in the logs shows that key as the user instead of a person. User attribution adds a label to the credentials on each request, and Package Firewall records that label as the user on the event. Attribution is informational. Your API key and secret still control access. The label does not grant or restrict any permission, and rotating the key does not change how attribution works. You can view the attributed user on each event and query the logs by attributed user. See View Package Firewall logs to learn more.

How the label reaches Package Firewall

A client puts the label in the Basic-auth username, using the following format. The password stays your API secret.

base64(base64("userattr:" + <label>) + ":" + <api-key>)

Package Firewall decodes the username, restores your API key to authenticate the request, and records the label as the user on the event. The inner base64 layer keeps the label separate from the API key, so the label itself can contain any character. Package Firewall treats a username that fails to decode, or one whose decoded value does not begin with userattr:, as a plain API key. The request authenticates exactly as it would without attribution, and the log records no attributed user. Attribution works through the credentials, so any client that can vary the username per developer can attribute its requests.

Where attribution is available

Sonatype Nexus Repository and Google Artifact Registry send the credentials you stored on the repository with every request, so requests through those integrations have no per-developer label. Endor Patches requests are served from a different route than the firewall, so attribution does not apply to them.

Attribute requests from MDM deployments

The MDM scripts attribute traffic by default. They build a <console-user>@<machine> label at install time and encode it into the credentials they write for npm, pnpm, yarn, bun, pip, uv, Go, Maven, and NuGet. See MDM deployment to generate and deploy the scripts. To attribute traffic differently, for example by email address or by an asset tag from your device inventory, fork the MDM scripts repository and change the ENDOR_ATTR_LABEL assignment. It lives in package-firewall/bash/generate.sh for macOS and Linux, and in package-firewall/powershell/templates/envvars.ps1 for Windows. The two environment variables the scripts write hold the same value at two encoding stages, not two halves of the label. ENDOR_ATTR_LABEL holds the entire label, and ENDOR_ATTR_USER holds the Basic-auth username derived from it. Package Firewall never combines them, and the attributed user in the logs is always exactly the label.

Attribute requests from JFrog Artifactory

A remote repository stores one set of credentials and sends them on every request, so every developer looks the same to Package Firewall. An Artifactory worker adds the label. It runs inside Artifactory on each request, reads the Artifactory user who made the request, and rewrites the outgoing authorization header to include that user as the label.

Before you begin

Workers service: Your JFrog subscription must include the Workers service. For availability, refer to Workers overview.
Individual developer accounts: Each developer must authenticate to Artifactory with their own account or token. The label comes from the Artifactory user on the request, so developers who share one service account all get the same label.
A configured remote repository: Set up the repository first. See Configure the Package Firewall with JFrog Artifactory to learn more.
An Endor Labs API key: Use the API key and secret you created for the remote repository.

Create the worker

In JFrog, create two worker secrets that hold your Endor Labs credentials. Name them ENDOR_API_KEY_ID and ENDOR_API_SECRET.
Create a worker that uses the Before Remote Info event, which is the event that can add request headers before Artifactory contacts the remote source. For more information, refer to Configure Workers for custom flows.
Attach the worker to each remote repository you route through Package Firewall.

Enter the following code as the worker body.

// Workers has no base64 library, so encode the credentials here.
function b64(value: string): string {
  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
  const bytes = encodeURIComponent(value).replace(
    /%([0-9A-F]{2})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16))
  );
  let result = "";
  for (let i = 0; i < bytes.length; i += 3) {
    const n = (bytes.charCodeAt(i) << 16) |
              (bytes.charCodeAt(i + 1) << 8) |
              bytes.charCodeAt(i + 2);

    result += chars[(n >>> 18) & 63] + chars[(n >>> 12) & 63];
    result += i + 1 < bytes.length ? chars[(n >>> 6) & 63] : "=";
    result += i + 2 < bytes.length ? chars[n & 63] : "=";
  }
  return result;
}

export default async (
  context: PlatformContext,
  data: BeforeRemoteInfoRequest
): Promise<BeforeRemoteInfoResponse> => {
  const keyId = context.secrets.get("ENDOR_API_KEY_ID");
  const secret = context.secrets.get("ENDOR_API_SECRET");
  // The user identifier is a path that ends in the Artifactory username.
  const label = data.userContext?.id?.split("/").pop() ?? "";

  const requestHeaders: { [key: string]: Header } = {};

  // Without a label, send nothing and let the repository credentials authenticate.
  if (label && keyId && secret) {
    const username = b64(`${b64(`userattr:${label}`)}:${keyId}`);
    requestHeaders["Authorization"] = { value: [`Basic ${b64(`${username}:${secret}`)}`] };
  }

  return <any>{
    message: "proceed",
    status: ActionStatus.PROCEED,
    headers: requestHeaders,
  };
};

Install the test package through the repository. See Verify your setup to learn more.
Confirm that the block event shows the Artifactory username as the attributed user. Package Firewall records an event only when it blocks, warns about, or curates a package. See View Package Firewall logs to learn more.

The worker sends the Artifactory username as the label, which it takes from the last segment of the user identifier on the request. When developers sign in to Artifactory through single sign-on, the username is usually their email address. To report on something else, such as a team name, map the username to that value inside the worker before you encode it.

Attribute requests from direct integrations

Direct integration writes the Package Firewall URL and credentials into each package manager configuration file, so you control the username on every client. To attribute requests, build an attributed username from a label and your API key, and use it in place of your API key. Your API secret remains the same. See How the label reaches Package Firewall to learn how Package Firewall reads the username. Build a separate attributed username for each developer, and add it to their user-level configuration file. In a shared project-level file, Package Firewall records the same label for every developer who uses the project.

Run the following command to build the attributed username. Replace <label> with the label to record for each request, such as doe@deer.ai, and <api-key> with your API key. See Create an API key for the Package Firewall to create a key, and Choose a label to pick a label convention.
- macOS / Linux
- Windows
LABEL='<label>' API_KEY='<api-key>' printf '%s:%s' "$(printf '%s' "userattr:$LABEL" | base64 | tr -d '\n')" "$API_KEY" | base64 | tr -d '\n'; echo
$label = '<label>' $apiKey = '<api-key>' $inner = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("userattr:$label")) [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("${inner}:$apiKey"))
The command prints the attributed username. If the label contains an apostrophe, write it as '\'' in Bash or '' in PowerShell.
Generate the configuration for your package manager client with the configuration wizard, and follow its steps. See Configure your package manager configuration file to learn more. Use the attributed username wherever the steps use <api-key>. The following table shows where to replace the API key for each package manager client.
Install the test package for your package manager client. See Verify your setup to learn more.
Confirm that the block event shows your label as the attributed user. See View Package Firewall logs to learn more.

If you write your own deployment scripts, use the MDM scripts as an example. They build the attributed username the same way.

Choose a label

The following labels are examples of conventions you can adopt, not a list the platform defines. Package Firewall stores the label as one string and never parses it, so the convention you pick is the one your reporting has to live with. Use a single convention across the fleet. A mix of formats means every query against spec.user has to account for each one. Keep the half of the label that stays stable for whatever you report on. If you report by person, hold the person half steady even when hardware changes. If you report by device, hold the device half steady even when the user changes. On a shared virtual machine the device half stops identifying anyone, so only the person half identifies who made the request.

Label constraints

Package Firewall doesn’t interpret the label. It stores and displays the value and never parses it, so no character in the label has a special meaning. The @ in the default label is a convention of the MDM scripts, not a separator the platform interprets.

Character set: The label must be valid UTF-8. Package Firewall drops a label that is not valid UTF-8. The request still authenticates and the log still records the event, but with no attributed user.
Delimiters: Every character is safe, including :, @, /, and spaces, and no delimiter is unsupported. The label is base64-encoded before the client sends it, so no character can break the format. A label such as team:platform/doe@laptop-14 reaches the logs exactly as written.
Length: Package Firewall imposes no maximum label length, and the Endor Labs service accepts labels of at least 16 KB. In practice, your own network sets the limit. HTTP proxies commonly cap a single header line at 8 KB. Every client sends the attributed username and API secret in a Basic authorization header, which is about 2.4 times the label length. A label under 1 KB stays far below an 8 KB header line.

Introduction

Set up

Configure

Operate