mirror of
https://github.com/sol1/rustguac.git
synced 2026-09-10 17:47:13 +00:00
Dave Kempe
0d69e8fed4
Three pieces of v1.6.0 work that happened together and are easier to
review as one save point.
Rename: Address Book → Connections
- static/addressbook.html renamed to static/connections.html
- Nav links, page titles, empty states, onboarding, and prose updated
across all 8 static pages (connections, admin, docs, index,
recordings, reports, sessions, tokens).
- README, CLAUDE.md, and every file under docs/ updated.
- src/main.rs: connections.html added to the branded-page map and
route list; /addressbook.html returns a 308 permanent redirect so
existing bookmarks keep working.
- Backend API paths, Rust types, and Vault storage paths are
deliberately unchanged — internal only.
Folder allowed_groups picker
- New SQLite table `seen_groups` tracks OIDC groups observed in any
user login; OIDC callback upserts after extracting groups.
- `GET /api/auth/known-groups` (admin-only) returns the union of
group_role_mappings and seen_groups.
- `GET /api/addressbook/folders/{scope}/{folder}/config` adds the
missing endpoint the frontend was already calling — existing
allowed_groups now prefill the edit-folder modal.
- Folder modal swaps the free-text comma-separated input for a chip
picker with a themed combobox dropdown: autocomplete over known
groups, keyboard nav, "+ add custom" row for unlisted groups.
Active session visibility (GitHub #102)
- `GET /api/sessions` scopes to the caller's own sessions by default;
`?all=true` lets admins opt in (used by the Sessions page).
- `GET /api/sessions/{id}` and the thumbnail GET/PUT endpoints are
now owner-or-admin, returning 404 for other callers so session
existence isn't leaked.
- Connections' Active Sessions strip is now always owner-scoped —
admins still manage everyone via the Sessions page.
80 lines
3.5 KiB
Markdown
80 lines
3.5 KiB
Markdown
# Reports
|
|
|
|
The reports page provides usage analytics and session history for your rustguac deployment. It is available to users with the **poweruser** role or higher.
|
|
|
|
## Summary cards
|
|
|
|
The top of the reports page shows four summary metrics:
|
|
|
|
- **Total Sessions** -- lifetime count of all sessions (within the retention window)
|
|
- **Total Hours** -- cumulative session duration in hours
|
|
- **Unique Users** -- number of distinct users who have created sessions
|
|
- **Active Now** -- sessions currently in progress
|
|
|
|
## Session history
|
|
|
|
A searchable, sortable table of all past and current sessions. Each row includes the user who created the session, the connections entry and folder (if applicable), session type (SSH, RDP, VNC, Web), hostname, start time, duration, status, and a link to the recording if one exists.
|
|
|
|
The table supports:
|
|
|
|
- **Text filter** -- type in the filter box to narrow results across all visible columns
|
|
- **Column sorting** -- click any column header to sort ascending/descending
|
|
- **Pagination** -- navigate through results 100 at a time
|
|
|
|
### CSV export
|
|
|
|
Click the **Export CSV** button next to the filter input to download the full session history as a CSV file. The export respects the same filters available via the API (user, entry, type, date range) and returns all matching rows (up to 100,000).
|
|
|
|
The CSV columns are: Session ID, Type, Hostname, Username, User, Entry, Folder, Started, Ended, Duration (secs), Status, Recording.
|
|
|
|
## Leaderboards
|
|
|
|
Two side-by-side panels at the bottom of the page:
|
|
|
|
- **Top Connections** -- most frequently used connections, ranked by session count, with total hours
|
|
- **Top Users** -- most active users, ranked by session count, with total hours and last session time
|
|
|
|
## Access control
|
|
|
|
All report endpoints require the **poweruser** role (level 3) or higher. Users with the **operator** or **viewer** role will receive a 403 Forbidden response.
|
|
|
|
## Session history retention
|
|
|
|
Session history is retained for a configurable number of days. Old entries are automatically cleaned up once per hour. Configure this in your `config.toml`:
|
|
|
|
```toml
|
|
session_history_retention_days = 90 # default: 90, set to 0 to keep forever
|
|
```
|
|
|
|
## API endpoints
|
|
|
|
All endpoints require authentication (API key, user token, or OIDC session cookie) with poweruser+ role.
|
|
|
|
| Method | Path | Description |
|
|
|--------|------|-------------|
|
|
| `GET` | `/api/reports/summary` | Summary statistics (total sessions, hours, unique users, active now) |
|
|
| `GET` | `/api/reports/sessions` | Paginated session history with filters |
|
|
| `GET` | `/api/reports/sessions/csv` | Export session history as CSV download |
|
|
| `GET` | `/api/reports/top-connections` | Most-used connections leaderboard |
|
|
| `GET` | `/api/reports/top-users` | Most active users leaderboard |
|
|
|
|
### Query parameters for session endpoints
|
|
|
|
| Parameter | Description |
|
|
|-----------|-------------|
|
|
| `user` | Filter by username (partial match) |
|
|
| `entry` | Filter by connections entry name (partial match) |
|
|
| `type` | Filter by session type: `ssh`, `rdp`, `vnc`, `web` |
|
|
| `from` | Start date filter (ISO 8601, e.g. `2025-01-01T00:00:00Z`) |
|
|
| `to` | End date filter (ISO 8601) |
|
|
| `limit` | Page size (default 100, max 1000; ignored for CSV export) |
|
|
| `offset` | Page offset (default 0; ignored for CSV export) |
|
|
|
|
### Example: export last month's SSH sessions
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer YOUR_API_KEY" \
|
|
"https://console.example.com/api/reports/sessions/csv?type=ssh&from=2025-02-01T00:00:00Z&to=2025-03-01T00:00:00Z" \
|
|
-o ssh-sessions.csv
|
|
```
|