Skip to content

Add -project flag for UUID-based project identification #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MedUnes merged 1 commit into from
Jun 30, 2026
Merged

Add -project flag for UUID-based project identification #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 52 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,13 @@ in [OWASP Dependency-Track](https://dependencytrack.org/).
This tool bridges the gap between simple API uploads and full CI/CD lifecycle management by handling **version sprawl**,
**active states**, and **latest version tagging** in a single execution.

## 🚀 Why this tool? (The Gap)
You can identify a project either by `PROJECT_NAME` + `VERSION` or by its stable **UUID** (via `-project`). Because the
UUID is stable, it keeps working across project **renames**: `-upload` targets the project directly, and
`-list`/`-clean`/`-latest` re-resolve the project's current name from the UUID on each run. Note that the lifecycle
operations (`-clean`/`-latest`) then act on every version sharing that resolved name, exactly like name-based mode, the
UUID selects the project, not a narrower scope.

## Why this tool? (The Gap)

If you simply use `curl` to upload an SBOM to Dependency-Track, you encounter two major problems over time. These are
well-documented pain points in the community:
Expand Down Expand Up @@ -48,7 +54,7 @@ There is no built-in native feature to "keep only the last X versions" or "purge
* **Our Solution:** While we don't delete data (auditors hate that!), our tool effectively "archives" old versions by
deactivating them, solving the noise issue without destroying history.

## 🧠 Concepts: Active vs. Latest
## Concepts: Active vs. Latest

Understanding these flags is critical for a clean dashboard:

Expand All @@ -57,7 +63,7 @@ Understanding these flags is critical for a clean dashboard:
| **Active** | Indicates this version is currently deployed/supported. | **Critical.** Only "Active" versions contribute to Portfolio Metrics and trigger Vulnerability Alerts. |
| **Latest** | Indicates this is the most current version of the project. | **Visual & Analytical.** Used as the baseline for "Outdated Component" analysis and marked with a badge in the UI. |

## 📦 Installation
## Installation

Since this is a single-file Go program, you can run it directly or build a binary.

Expand Down Expand Up @@ -86,7 +92,7 @@ go build -o dtrack-cli main.go

```

## 🛠 Usage Scenarios
## Usage Scenarios

### Scenario 1: The "Golden Path" (CI Pipeline)

Expand Down Expand Up @@ -152,7 +158,7 @@ dtrack-cli -clean -latest $DT_API_KEY "My-Web-App" "v2.0"

### Scenario 5: Debugging HTTP issues

**Goal:** An upload or lookup is failing in a way that isn't obvious — perhaps the base URL is wrong, an upstream proxy
**Goal:** An upload or lookup is failing in a way that isn't obvious, perhaps the base URL is wrong, an upstream proxy
is rewriting requests, or the server is responding with HTML instead of JSON. Reach for `-verbose` to surface the actual
request URL, response status, and a body preview (first 512 bytes).

Expand All @@ -169,30 +175,56 @@ dtrack-cli -verbose -list $DT_API_KEY "My-Web-App"
[verbose] Body (preview): [{"uuid":"abc-123","name":"My-Web-App","version":"v1.2.0",...}]
```

## 🚩 Flag Reference
### Scenario 6: Using a Project UUID

**Goal:** Identify the project by its UUID instead of `PROJECT_NAME` + `VERSION`. This is handy when a project may be
renamed, or when your pipeline already stores the UUID. The UUID identifies one specific version, so only the `API_KEY`
positional argument is needed.

```bash
# Upload by UUID (no name/version needed), sends the BOM with project=<uuid>
dtrack-cli -upload -project abc-123-def -file ./build/bom.json $DT_API_KEY

# Full CI mode by UUID (upload + latest + clean)
dtrack-cli -ci -project abc-123-def -file ./build/bom.json $DT_API_KEY

# List sibling versions (resolves UUID -> project name, then lists all versions)
dtrack-cli -list -project abc-123-def $DT_API_KEY

# Clean + latest by UUID
dtrack-cli -clean -latest -project abc-123-def $DT_API_KEY
```

| Flag | Description | Requirement |
|-----------|---------------------------------------------------------------------------------|---------------------------------------|
| `-upload` | Uploads the file specified by `-file`. | Requires `VERSION` argument. |
| `-list` | Displays a table of all versions for this project. | |
| `-latest` | Marks the target version as `isLatest=true` and unsets it for others. | Requires `VERSION` argument. |
| `-clean` | Marks the target version as `active=true` and **all others** as `active=false`. | Requires `VERSION` argument. |
| `-ci` | **Recommended.** Shortcut for `-upload -latest -clean`. | Requires `VERSION` argument. |
| `-url` | Base URL of your Dependency-Track instance. Trailing slashes are stripped. | Default: `https://dtrack.example.com` |
| `-file` | Path to the SBOM file. | Default: `sbom.json` |
| `-verbose` | Prints HTTP request/response details (method, URL, status, body preview) for debugging. | Optional, additive to any other flag. |
For `-list` / `-latest` / `-clean`, the tool first calls `GET /api/v1/project/<uuid>` to resolve the UUID into the
project's name and version, then runs the usual name-based list/patch flow, so these lifecycle operations still act on
all versions sharing that name (see the note in the intro). If you also pass positional `PROJECT_NAME`/`VERSION`
alongside `-project`, they are ignored (with a warning).

## Flag Reference

| Flag | Description | Requirement |
|------------|------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|
| `-upload` | Uploads the file specified by `-file`. | Requires `VERSION` argument. |
| `-list` | Displays a table of all versions for this project. | |
| `-latest` | Marks the target version as `isLatest=true` and unsets it for others. | Requires `VERSION` argument. |
| `-clean` | Marks the target version as `active=true` and **all others** as `active=false`. | Requires `VERSION` argument. |
| `-ci` | **Recommended.** Shortcut for `-upload -latest -clean`. | Requires `VERSION` argument. |
| `-url` | Base URL of your Dependency-Track instance. Trailing slashes are stripped. | Default: `https://dtrack.example.com` |
| `-file` | Path to the SBOM file. | Default: `sbom.json` |
| `-verbose` | Prints HTTP request/response details (method, URL, status, body preview) for debugging. | Optional, additive to any other flag. |
| `-project` | Identify the project by UUID instead of `PROJECT_NAME` + `VERSION`. When set, the positional name/version are ignored. | Replaces the `PROJECT_NAME`/`VERSION` positionals. |

## ⚠️ Requirements

* **Go 1.21+** (uses `slices` and `cmp` packages).
* **Network:** Access to the Dependency-Track API.
* **Permissions:** The API Key used must have `BOM_UPLOAD` and `PROJECT_CREATION_UPLOAD` permissions.

## 🧪 Development
## Development

* `make build` — produce the static binary.
* `make test` — run `go test -v -race ./...`.
* `make build`: produce the static binary.
* `make test`: run `go test -v -race ./...`.

## 📚 References
## References

* Dependency Track REST API documentation https://docs.dependencytrack.org/integrations/rest-api/
Loading
Loading