feat(scanner): Complete PoE implementation with Windows compatibility fix
- Fix namespace conflicts (Subgraph → PoESubgraph) - Add hash sanitization for Windows filesystem (colon → underscore) - Update all test mocks to use It.IsAny<>() - Add direct orchestrator unit tests - All 8 PoE tests now passing (100% success rate) - Complete SPRINT_3500_0001_0001 documentation Fixes compilation errors and Windows filesystem compatibility issues. Tests: 8/8 passing Files: 8 modified, 1 new test, 1 completion report 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
master
460
docs/cli/admin-reference.md
Normal file
460
docs/cli/admin-reference.md
Normal file
@@ -0,0 +1,460 @@
|
||||
# stella admin - Administrative Operations Reference
|
||||
|
||||
**Sprint:** SPRINT_4100_0006_0005 - Admin Utility Integration
|
||||
|
||||
## Overview
|
||||
|
||||
The `stella admin` command group provides administrative operations for platform management. These commands require elevated authentication and are used for policy management, user administration, feed configuration, and system maintenance.
|
||||
|
||||
## Authentication
|
||||
|
||||
Admin commands require one of the following authentication methods:
|
||||
|
||||
1. **OpTok with admin scopes** (recommended for production):
|
||||
```bash
|
||||
stella auth login
|
||||
# Obtain OpTok with admin.* scopes
|
||||
stella admin policy export
|
||||
```
|
||||
|
||||
2. **Bootstrap API key** (for initial setup before Authority configured):
|
||||
```bash
|
||||
export STELLAOPS_BOOTSTRAP_KEY="bootstrap-key-from-backend-config"
|
||||
stella admin users add admin@example.com --role admin
|
||||
```
|
||||
|
||||
### Required Scopes
|
||||
|
||||
| Command Group | Required Scope | Purpose |
|
||||
|---------------|----------------|---------|
|
||||
| `stella admin policy` | `admin.policy` | Policy management operations |
|
||||
| `stella admin users` | `admin.users` | User administration |
|
||||
| `stella admin feeds` | `admin.feeds` | Feed management |
|
||||
| `stella admin system` | `admin.platform` | System operations |
|
||||
|
||||
## Command Reference
|
||||
|
||||
### stella admin policy
|
||||
|
||||
Policy management commands for exporting, importing, and validating platform policies.
|
||||
|
||||
#### stella admin policy export
|
||||
|
||||
Export the active policy snapshot to a file or stdout.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin policy export [--output <path>] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-o, --output <path>` - Output file path (stdout if omitted)
|
||||
- `-v, --verbose` - Enable verbose output
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Export to stdout
|
||||
stella admin policy export
|
||||
|
||||
# Export to file
|
||||
stella admin policy export --output policy-backup.yaml
|
||||
|
||||
# Export with timestamp
|
||||
stella admin policy export --output backup-$(date +%F).yaml
|
||||
```
|
||||
|
||||
#### stella admin policy import
|
||||
|
||||
Import policy from a YAML or JSON file.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin policy import --file <path> [--validate-only] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-f, --file <path>` - Policy file to import (required)
|
||||
- `--validate-only` - Validate without importing
|
||||
- `-v, --verbose` - Enable verbose output
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Validate policy before importing
|
||||
stella admin policy import --file new-policy.yaml --validate-only
|
||||
|
||||
# Import policy
|
||||
stella admin policy import --file new-policy.yaml
|
||||
```
|
||||
|
||||
#### stella admin policy validate
|
||||
|
||||
Validate a policy file without importing.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin policy validate --file <path> [--verbose]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
stella admin policy validate --file policy.yaml
|
||||
```
|
||||
|
||||
#### stella admin policy list
|
||||
|
||||
List all policy revisions.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin policy list [--format <format>] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--format <format>` - Output format: `table` (default), `json`
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# List as table
|
||||
stella admin policy list
|
||||
|
||||
# List as JSON
|
||||
stella admin policy list --format json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella admin users
|
||||
|
||||
User management commands for adding, removing, and updating users.
|
||||
|
||||
#### stella admin users list
|
||||
|
||||
List platform users.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin users list [--role <role>] [--format <format>] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--role <role>` - Filter by role
|
||||
- `--format <format>` - Output format: `table` (default), `json`
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# List all users
|
||||
stella admin users list
|
||||
|
||||
# List all admins
|
||||
stella admin users list --role admin
|
||||
|
||||
# List as JSON
|
||||
stella admin users list --format json
|
||||
```
|
||||
|
||||
#### stella admin users add
|
||||
|
||||
Add a new user to the platform.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin users add <email> --role <role> [--tenant <id>] [--verbose]
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `<email>` - User email address
|
||||
|
||||
**Options:**
|
||||
- `-r, --role <role>` - User role (required)
|
||||
- `-t, --tenant <id>` - Tenant ID (default if omitted)
|
||||
|
||||
**Available Roles:**
|
||||
- `admin` - Full platform access
|
||||
- `security-engineer` - Security operations
|
||||
- `developer` - Development access
|
||||
- `viewer` - Read-only access
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Add admin user
|
||||
stella admin users add admin@example.com --role admin
|
||||
|
||||
# Add security engineer for specific tenant
|
||||
stella admin users add alice@example.com --role security-engineer --tenant acme-corp
|
||||
```
|
||||
|
||||
#### stella admin users revoke
|
||||
|
||||
Revoke user access.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin users revoke <email> [--confirm] [--verbose]
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `<email>` - User email address
|
||||
|
||||
**Options:**
|
||||
- `--confirm` - Confirm revocation (required for safety)
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Revoke user (requires --confirm)
|
||||
stella admin users revoke bob@example.com --confirm
|
||||
```
|
||||
|
||||
**Note:** The `--confirm` flag is required to prevent accidental user removal.
|
||||
|
||||
#### stella admin users update
|
||||
|
||||
Update user role.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin users update <email> --role <role> [--verbose]
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `<email>` - User email address
|
||||
|
||||
**Options:**
|
||||
- `-r, --role <role>` - New user role (required)
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Promote user to admin
|
||||
stella admin users update alice@example.com --role admin
|
||||
|
||||
# Change to viewer role
|
||||
stella admin users update bob@example.com --role viewer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella admin feeds
|
||||
|
||||
Advisory feed management commands.
|
||||
|
||||
#### stella admin feeds list
|
||||
|
||||
List configured advisory feeds.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin feeds list [--format <format>] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--format <format>` - Output format: `table` (default), `json`
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# List feeds as table
|
||||
stella admin feeds list
|
||||
|
||||
# List feeds as JSON
|
||||
stella admin feeds list --format json
|
||||
```
|
||||
|
||||
#### stella admin feeds status
|
||||
|
||||
Show feed synchronization status.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin feeds status [--source <id>] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-s, --source <id>` - Filter by source ID (all if omitted)
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Show status for all feeds
|
||||
stella admin feeds status
|
||||
|
||||
# Show status for specific feed
|
||||
stella admin feeds status --source nvd
|
||||
```
|
||||
|
||||
#### stella admin feeds refresh
|
||||
|
||||
Trigger feed refresh.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin feeds refresh [--source <id>] [--force] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-s, --source <id>` - Refresh specific source (all if omitted)
|
||||
- `--force` - Force refresh (ignore cache)
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Refresh all feeds
|
||||
stella admin feeds refresh
|
||||
|
||||
# Force refresh specific feed
|
||||
stella admin feeds refresh --source nvd --force
|
||||
|
||||
# Refresh OSV feed
|
||||
stella admin feeds refresh --source osv
|
||||
```
|
||||
|
||||
#### stella admin feeds history
|
||||
|
||||
Show feed synchronization history.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin feeds history --source <id> [--limit <n>] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-s, --source <id>` - Source ID (required)
|
||||
- `-n, --limit <n>` - Limit number of results (default: 10)
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Show last 10 syncs for NVD
|
||||
stella admin feeds history --source nvd
|
||||
|
||||
# Show last 50 syncs for OSV
|
||||
stella admin feeds history --source osv --limit 50
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### stella admin system
|
||||
|
||||
System management and health commands.
|
||||
|
||||
#### stella admin system status
|
||||
|
||||
Show system health status.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin system status [--format <format>] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--format <format>` - Output format: `table` (default), `json`
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Show status as table
|
||||
stella admin system status
|
||||
|
||||
# Show status as JSON
|
||||
stella admin system status --format json
|
||||
```
|
||||
|
||||
#### stella admin system info
|
||||
|
||||
Show system version, build, and configuration information.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella admin system info [--verbose]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
stella admin system info
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
Admin commands can be configured via `appsettings.admin.yaml`:
|
||||
|
||||
```yaml
|
||||
StellaOps:
|
||||
Backend:
|
||||
BaseUrl: "https://api.stellaops.example.com"
|
||||
Auth:
|
||||
OpTok:
|
||||
Enabled: true
|
||||
|
||||
Admin:
|
||||
DefaultTenant: "default"
|
||||
RequireConfirmation: true
|
||||
AuditLog:
|
||||
Enabled: true
|
||||
OutputPath: "~/.stellaops/admin-audit.jsonl"
|
||||
```
|
||||
|
||||
See `etc/appsettings.admin.yaml.example` for full configuration options.
|
||||
|
||||
## Backend API Endpoints
|
||||
|
||||
Admin commands call the following backend APIs:
|
||||
|
||||
| Endpoint | Method | Command |
|
||||
|----------|--------|---------|
|
||||
| `/api/v1/admin/policy/export` | GET | `stella admin policy export` |
|
||||
| `/api/v1/admin/policy/import` | POST | `stella admin policy import` |
|
||||
| `/api/v1/admin/policy/validate` | POST | `stella admin policy validate` |
|
||||
| `/api/v1/admin/policy/revisions` | GET | `stella admin policy list` |
|
||||
| `/api/v1/admin/users` | GET | `stella admin users list` |
|
||||
| `/api/v1/admin/users` | POST | `stella admin users add` |
|
||||
| `/api/v1/admin/users/{email}` | DELETE | `stella admin users revoke` |
|
||||
| `/api/v1/admin/users/{email}` | PATCH | `stella admin users update` |
|
||||
| `/api/v1/admin/feeds` | GET | `stella admin feeds list` |
|
||||
| `/api/v1/admin/feeds/status` | GET | `stella admin feeds status` |
|
||||
| `/api/v1/admin/feeds/{id}/refresh` | POST | `stella admin feeds refresh` |
|
||||
| `/api/v1/admin/feeds/{id}/history` | GET | `stella admin feeds history` |
|
||||
| `/api/v1/admin/system/status` | GET | `stella admin system status` |
|
||||
| `/api/v1/admin/system/info` | GET | `stella admin system info` |
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Authentication Required**: All admin commands require valid OpTok or bootstrap key
|
||||
2. **Scope Validation**: Backend validates admin.* scopes for all operations
|
||||
3. **Audit Logging**: All admin operations are logged to audit trail
|
||||
4. **Confirmation for Destructive Ops**: Commands like `revoke` require `--confirm` flag
|
||||
5. **Bootstrap Mode**: Bootstrap key should only be used for initial setup
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Authentication Errors
|
||||
|
||||
```
|
||||
HTTP 401: Unauthorized
|
||||
```
|
||||
|
||||
**Solution**: Ensure you have a valid OpTok with admin scopes:
|
||||
```bash
|
||||
stella auth login
|
||||
stella admin policy export
|
||||
```
|
||||
|
||||
### Missing Scopes
|
||||
|
||||
```
|
||||
HTTP 403: Forbidden - insufficient scopes
|
||||
```
|
||||
|
||||
**Solution**: Request OpTok with required admin.* scopes from platform administrator.
|
||||
|
||||
### Backend API Not Available
|
||||
|
||||
```
|
||||
HTTP Error: Connection refused
|
||||
```
|
||||
|
||||
**Solution**: Verify backend URL in configuration:
|
||||
```bash
|
||||
export STELLAOPS_BACKEND__BASEURL="https://api.stellaops.example.com"
|
||||
stella admin system status
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [CLI Reference](../09_API_CLI_REFERENCE.md)
|
||||
- [Authority Documentation](../11_AUTHORITY.md)
|
||||
- [Operational Procedures](../operations/administration.md)
|
||||
Reference in New Issue
Block a user