diff --git a/PROJECT.md b/PROJECT.md new file mode 100644 index 0000000..f9bcf5e --- /dev/null +++ b/PROJECT.md @@ -0,0 +1,45 @@ +# Project: harbor-ctl + +## Purpose + +Command-line interface for managing Harbor container registry. Provides quick access to common operations without requiring the web UI or manual API calls. + +## Scope + +### In Scope + +- Project, repository, and artifact listing +- Vulnerability scanning and reporting +- SBOM retrieval and display +- Tag management +- Artifact deletion +- Project configuration (auto-scan, auto-sbom) + +### Out of Scope + +- User/group management (admin-only, rare) +- System configuration (one-time setup) +- Replication rule creation (complex, rare) +- Garbage collection triggers (scheduled) + +## Success Criteria + +- Modular package structure for maintainability +- No external dependencies (stdlib only) +- All common daily operations accessible via CLI +- Clear, scannable output for terminal use +- Exit codes suitable for scripting +- Credentials managed securely (no hardcoding) + +## Constraints + +- Python 3.10+ stdlib only +- Harbor API v2.0 compatibility +- Must work in minimal environments (no pip install required) +- Legacy single-file script maintained for compatibility + +## Assumptions + +- Harbor instance is accessible over HTTPS +- User has appropriate permissions for requested operations +- Credentials file follows established format when present diff --git a/README.md b/README.md new file mode 100644 index 0000000..6d961e8 --- /dev/null +++ b/README.md @@ -0,0 +1,104 @@ +# harbor-ctl + +CLI utility for interacting with Harbor container registry API. + +## Installation + +```sh +# Run directly from source +PYTHONPATH=src python3 -m harbor + +# Or install in development mode +pip install -e . + +# Or use the legacy single-file script +./harbor-ctl.py +``` + +## Usage + +``` +python -m harbor [options] +``` + +## Commands + +| Command | Description | +|---------|-------------| +| `projects` | List all projects | +| `repos ` | List repositories in a project | +| `artifacts ` | List artifacts in a repository | +| `info ` | Show artifact details | +| `vulns ` | List vulnerabilities | +| `scan ` | Trigger vulnerability scan | +| `tags ` | List or manage tags | +| `sbom ` | Get SBOM for artifact | +| `delete ` | Delete artifact or tag | +| `config ` | View/modify project settings | + +## Authentication + +Credentials are loaded in priority order: + +1. CLI arguments (`-u`, `-p`) +2. Secrets file (`/opt/ansible/secrets/harbor/credentials.json`) +3. Environment variables (`HARBOR_USER`, `HARBOR_PASS`) + +## Examples + +```sh +# List projects +python -m harbor projects + +# List repositories in 'library' project +python -m harbor repos library + +# Show latest artifact details +python -m harbor info library myapp + +# Show artifact by tag +python -m harbor info library myapp -d v1.0.0 + +# List high severity vulnerabilities +python -m harbor vulns library myapp -s high + +# Filter vulnerabilities by package +python -m harbor vulns library myapp -P openssl + +# Trigger scan and wait for completion +python -m harbor scan library myapp --wait + +# Add tag to artifact +python -m harbor tags library myapp -a production + +# Show SBOM +python -m harbor sbom library myapp + +# Show project settings +python -m harbor config library --show + +# Enable auto-scan +python -m harbor config library --auto-scan true +``` + +## Project Structure + +``` +src/ +└── harbor/ + ├── __init__.py Package metadata + ├── __main__.py Entry point (python -m harbor) + ├── cli.py Argument parsing, main() + ├── client.py API client functions + ├── commands.py CLI command handlers + └── config.py Credentials loading +``` + +## Requirements + +- Python 3.10+ +- No external dependencies (stdlib only) + +## License + +MIT diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..130d813 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,69 @@ +# Roadmap + +## Phase 1: Foundation (Complete) + +Core functionality implemented: + +- [x] Project listing +- [x] Repository listing +- [x] Artifact listing and details +- [x] Vulnerability display with filtering +- [x] Scan triggering with wait +- [x] Tag management +- [x] SBOM retrieval +- [x] Artifact/tag deletion +- [x] Project configuration +- [x] CI pipeline (syntax + lint) +- [x] Modular package structure (`src/harbor/`) + +## Phase 2: Quality + +Code quality and maintainability improvements: + +- [x] Add type hints throughout +- [x] Modular code organization +- [ ] Add unit tests for core functions +- [ ] Add integration tests (mock API) +- [ ] Improve error messages +- [x] Add `--version` flag +- [ ] Add `--quiet` mode for scripting + +## Phase 3: Output + +Terminal output improvements: + +- [ ] Unicode status indicators +- [ ] Color output (with NO_COLOR support) +- [ ] Table alignment fixes +- [ ] Progress indicators for long operations +- [ ] JSON output mode for all commands + +## Phase 4: Features + +Additional functionality: + +- [ ] `labels` command - manage artifact labels +- [ ] `copy` command - copy artifact between repos +- [ ] `gc` command - show garbage collection status +- [ ] `replication` command - list replication rules/executions +- [ ] `quota` command - show project quota usage +- [ ] `audit` command - show audit logs +- [ ] Partial digest tab completion + +## Phase 5: Distribution + +Packaging and distribution: + +- [ ] pyproject.toml with entry points +- [ ] Installable package (`pip install .`) +- [ ] Man page generation +- [ ] Shell completions (bash/zsh/fish) + +## Dependencies + +``` +Phase 1 (done) ──> Phase 2 ─┬─> Phase 3 + └─> Phase 4 ──> Phase 5 +``` + +Phase 3 and 4 can proceed in parallel after Phase 2. diff --git a/TASKLIST.md b/TASKLIST.md new file mode 100644 index 0000000..2a7751e --- /dev/null +++ b/TASKLIST.md @@ -0,0 +1,43 @@ +# Task List + +Active, prioritized work items. + +## In Progress + +(none) + +## Next Up + +| # | Task | Notes | +|---|------|-------| +| 1 | Unit tests for `client.resolve_digest()` | Core function, good test candidate | +| 2 | Unit tests for `client.build_url()` | Simple, deterministic | +| 3 | Mock API tests for `commands.cmd_projects()` | Start with simplest command | +| 4 | Unicode status symbols in output | Replace dashes with box-drawing | +| 5 | Add `--quiet` mode for scripting | Suppress headers, minimal output | + +## Backlog + +| Task | Phase | +|------|-------| +| ANSI color support (with NO_COLOR) | 3 | +| JSON output mode for all commands | 3 | +| `labels` command | 4 | +| `copy` command | 4 | +| `quota` command | 4 | +| pyproject.toml with entry points | 5 | +| Shell completions | 5 | + +## Completed + +- [x] Initial implementation +- [x] CI pipeline setup +- [x] Empty response body handling fix +- [x] README documentation +- [x] PROJECT.md, ROADMAP.md, TODO.md created +- [x] Type hints for `api_request()` and `load_credentials()` +- [x] `--version` flag (`-V`) +- [x] `build_url()` helper function +- [x] `--verify-ssl` flag for SSL certificate verification +- [x] Modular package structure (`src/harbor/`) +- [x] Documentation updated for new structure diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..9cadf16 --- /dev/null +++ b/TODO.md @@ -0,0 +1,31 @@ +# TODO + +Intake buffer for ideas, issues, and unrefined tasks. + +## Ideas + +- Support for `.harborrc` config file in home directory +- Cache project/repo lists for faster tab completion +- Webhook management commands +- Robot account management +- Retention policy display +- Health check endpoint monitoring +- Multi-registry support (switch between registries) + +## Issues + +- SSL verification disabled globally (should be configurable) +- No timeout configuration for API calls +- Delete confirmation reads stdin (breaks piping) +- Partial digest matching fetches all artifacts (slow for large repos) + +## Questions + +- Should `--json` output be available on all commands? +- Should we support OIDC authentication? +- Worth adding `--dry-run` for destructive operations? + +## Debt + +- Error handling inconsistent across commands +- Some magic numbers (column widths, timeouts)