endorctl api update with a field mask to replace only the credential and leave the rest of the integration unchanged. Run the same command from your secret rotation job to rotate credentials on a schedule.
Before you begin
Make sure you have the following:- endorctl installed and authenticated to your tenant. See Install and configure endorctl to set it up.
- The Admin role in the namespace. For an automated job, use an API key with the Admin role. See Authorization roles to compare what each role can access.
- The new credential from your registry.
Credential fields by ecosystem
Each ecosystem stores its credential in a specific field. Use the field mask that matches the field your integration already uses. For Maven, PyPI, RubyGems, and NuGet, endorctl usestoken_auth first, then basic_auth, then the legacy user and password fields. Update only the field that your integration already uses. Writing a different field can leave scans on the old credential or break authentication.
AWS CodeArtifact integrations authenticate with an IAM role and store no secret, so they have nothing to rotate.
mTLS client certificates rotate the same way. Use the mtls.client_cert and mtls.client_key fields of the ecosystem, such as spec.mvn.mtls.client_cert. See Authenticate to private packages using mTLS to learn which ecosystems support mTLS.
Rotate a credential with endorctl
Replace the stored credential with the new value from your registry.-
List the package manager integrations in your namespace. Replace
<namespace>with your namespace.Stored credentials appear as<redacted>. The field that holds<redacted>is the field your integration uses. If more than one field shows<redacted>, the integration uses the first in this order:token_auth,basic_auth, then the legacypassword.An npm integration can store bothauth_tokenandtoken. When both show<redacted>, the integration usesauth_token. -
Note the
uuidof the integration and find its field mask in the credential fields table. -
Update the credential. Replace
<package-manager-uuid>with the UUID and<new-password>with the new credential. This example rotates the password of a Maven integration that usesbasic_auth.For another field, change the--field-maskvalue and nest the new value under the same path in-d. The username and every field outside the mask stay as they are.
Rotate a Google Artifact Registry service account key
A service account key is a JSON document, so build the request body withjq to escape it correctly. Replace <key-file> with the path to the new key file.
Rotate a credential from an automated job
Pass the new credential from an environment variable so that it doesn’t appear in shell history or job logs. This example reads an npm auth token fromNPM_AUTH_TOKEN.
PATCH request to /v1/namespaces/<namespace>/package-managers with the field mask in request.update_mask.
Verify the new credential
After every update, Endor Labs checks the registry and returns the result inspec.package_manager_status. For Google Artifact Registry and AWS CodeArtifact, the check authenticates with the stored credentials. For other registries, it confirms only that the registry host is reachable, and Gradle integrations aren’t checked.
To confirm that the new credential works, scan a project that resolves a dependency from the private registry. If the scan resolves the dependency, the rotation worked.
If spec.package_manager_status.state is STATE_FAIL, spec.package_manager_status.error_message describes the error.
Next steps
- See Private package manager integrations to set up an integration for another ecosystem.
- See endorctl api to learn more about the update command and its flags.