2ade509b63
- Cross-platform support (Windows/Linux) with Windows Updates and Winget - Added dependency confirmation workflow and refresh token authentication - New screenshots: History, Live Operations, Windows Agent Details - Local CLI features with terminal output and cache system - Updated known limitations - Proxmox integration is broken - Organized docs to docs/ folder and updated .gitignore - Probably introduced a dozen bugs with Windows agents - stay tuned
233 lines
7.1 KiB
Markdown
233 lines
7.1 KiB
Markdown
# RedFlag (Aggregator)
|
|
|
|
⚠️ PRIVATE DEVELOPMENT - NOT FOR PUBLIC USE
|
|
|
|
This is a private development repository for version retention only.
|
|
|
|
## Status
|
|
|
|
- **Active Development**: In progress
|
|
- **Not Production Ready**: Do not use
|
|
- **Breaking Changes Expected**: APIs will change
|
|
- **No Support Available**: This is not released software
|
|
|
|
## What This Is
|
|
|
|
A self-hosted, cross-platform update management platform built with:
|
|
|
|
- Go server backend + PostgreSQL
|
|
- React web dashboard with TypeScript
|
|
- Cross-platform agents (Linux APT/DNF/Docker, Windows Updates/Winget)
|
|
- Local CLI tools for agent management
|
|
- Update installation system with dependency management
|
|
- Refresh token authentication for stable agent identity
|
|
|
|
## What This Isn't
|
|
|
|
- Not ready for public use
|
|
- Not documented for external users
|
|
- Not supported or maintained for others
|
|
- Not stable (active development)
|
|
|
|
## Current Capabilities
|
|
|
|
### Working Features
|
|
- Server backend with REST API
|
|
- Cross-platform agent registration and check-in
|
|
- Update discovery for APT, DNF, Docker images, Windows Updates, and Winget packages
|
|
- Update approval workflow with dependency confirmation
|
|
- Web dashboard with agent management and real-time status
|
|
- Local CLI tools (--scan, --status, --list-updates, --export, --export=json/csv)
|
|
- Update installation system with dry-run dependency checking
|
|
- Beautiful terminal output with colors and severity indicators
|
|
- Local cache system for offline viewing of scan results
|
|
- Refresh token authentication for stable agent identity
|
|
- Event-sourced database architecture for scalability
|
|
|
|
### Known Limitations
|
|
- No rate limiting on API endpoints (security improvement needed)
|
|
- No real-time WebSocket updates
|
|
- Proxmox integration is broken (needs complete rewrite)
|
|
- Authentication system works but needs security hardening
|
|
|
|
## Screenshots
|
|
|
|
### Main Dashboard
|
|
|
|
Overview showing agent status, system metrics, and update statistics
|
|
|
|
### Updates Management
|
|
|
|
Comprehensive update listing with filtering, approval, and dependency confirmation
|
|
|
|
### Agent Details
|
|
|
|
Detailed agent information including system specs, last check-in, and individual update management
|
|
|
|
### Windows Agent Support
|
|
|
|
Cross-platform support for Windows Updates and Winget package management
|
|
|
|
### History & Audit Trail
|
|
|
|
Complete audit trail of all update activities and command execution
|
|
|
|
### Live Operations
|
|
|
|
Real-time view of update operations with success/failure tracking
|
|
|
|
### Docker Container Management
|
|
|
|
Docker-specific interface for container image updates and management
|
|
|
|
## For Developers
|
|
|
|
This repository contains:
|
|
|
|
- **Server backend code** (`aggregator-server/`)
|
|
- **Agent code** (`aggregator-agent/`)
|
|
- **Web dashboard** (`aggregator-web/`)
|
|
- **Database migrations** and configuration
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────┐
|
|
│ Web Dashboard │ React + TypeScript + TailwindCSS
|
|
└────────┬────────┘
|
|
│ HTTPS
|
|
┌────────▼────────┐
|
|
│ Server (Go) │ Production Ready with PostgreSQL
|
|
│ + PostgreSQL │
|
|
└────────┬────────┘
|
|
│ Pull-based (agents check in every 5 min)
|
|
┌────┴────┬────────┐
|
|
│ │ │
|
|
┌───▼──┐ ┌──▼──┐ ┌──▼───┐
|
|
│Linux │ │Linux│ │Linux │
|
|
│Agent │ │Agent│ │Agent │
|
|
└──────┘ └─────┘ └──────┘
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
RedFlag/
|
|
├── aggregator-server/ # Go server (Gin + PostgreSQL)
|
|
│ ├── cmd/server/ # Main entry point
|
|
│ ├── internal/
|
|
│ │ ├── api/ # HTTP handlers & middleware
|
|
│ │ ├── database/ # Database layer & migrations
|
|
│ │ ├── models/ # Data models
|
|
│ │ └── config/ # Configuration
|
|
│ └── go.mod
|
|
|
|
├── aggregator-agent/ # Go agent
|
|
│ ├── cmd/agent/ # Main entry point
|
|
│ ├── internal/
|
|
│ │ ├── client/ # API client
|
|
│ │ ├── installer/ # Update installers (APT, DNF, Docker)
|
|
│ │ ├── scanner/ # Update scanners (APT, Docker, DNF/RPM)
|
|
│ │ ├── system/ # System information collection
|
|
│ │ └── config/ # Configuration
|
|
│ └── go.mod
|
|
|
|
├── aggregator-web/ # React dashboard
|
|
├── docker-compose.yml # PostgreSQL for local dev
|
|
├── Makefile # Common tasks
|
|
└── README.md # This file
|
|
```
|
|
|
|
## Database Schema
|
|
|
|
Key Tables:
|
|
- `agents` - Registered agents with system metadata
|
|
- `update_packages` - Discovered updates
|
|
- `agent_commands` - Command queue for agents
|
|
- `update_logs` - Execution logs
|
|
- `agent_tags` - Agent tagging/grouping
|
|
|
|
## Configuration
|
|
|
|
### Server (.env)
|
|
```bash
|
|
SERVER_PORT=8080
|
|
DATABASE_URL=postgres://aggregator:aggregator@localhost:5432/aggregator?sslmode=disable
|
|
JWT_SECRET=change-me-in-production
|
|
CHECK_IN_INTERVAL=300 # seconds
|
|
OFFLINE_THRESHOLD=600 # seconds
|
|
```
|
|
|
|
### Agent (/etc/aggregator/config.json)
|
|
Auto-generated on registration:
|
|
```json
|
|
{
|
|
"server_url": "http://localhost:8080",
|
|
"agent_id": "uuid",
|
|
"token": "jwt-token",
|
|
"check_in_interval": 300
|
|
}
|
|
```
|
|
|
|
## Development
|
|
|
|
### Makefile Commands
|
|
```bash
|
|
make help # Show all commands
|
|
make db-up # Start PostgreSQL
|
|
make db-down # Stop PostgreSQL
|
|
make server # Run server (with auto-reload)
|
|
make agent # Run agent
|
|
make build-server # Build server binary
|
|
make build-agent # Build agent binary
|
|
make test # Run tests
|
|
make clean # Clean build artifacts
|
|
```
|
|
|
|
### Running Tests
|
|
```bash
|
|
cd aggregator-server && go test ./...
|
|
cd aggregator-agent && go test ./...
|
|
```
|
|
|
|
## API Usage
|
|
|
|
### List All Agents
|
|
```bash
|
|
curl http://localhost:8080/api/v1/agents
|
|
```
|
|
|
|
### Trigger Update Scan
|
|
```bash
|
|
curl -X POST http://localhost:8080/api/v1/agents/{agent-id}/scan
|
|
```
|
|
|
|
### List All Updates
|
|
```bash
|
|
# All updates
|
|
curl http://localhost:8080/api/v1/updates
|
|
|
|
# Filter by severity
|
|
curl http://localhost:8080/api/v1/updates?severity=critical
|
|
|
|
# Filter by status
|
|
curl http://localhost:8080/api/v1/updates?status=pending
|
|
```
|
|
|
|
### Approve an Update
|
|
```bash
|
|
curl -X POST http://localhost:8080/api/v1/updates/{update-id}/approve
|
|
```
|
|
|
|
## Security
|
|
|
|
- Agent Authentication: JWT tokens with 24h expiry
|
|
- Pull-based Model: Agents poll server (firewall-friendly)
|
|
- Command Validation: Whitelisted commands only
|
|
- TLS Required: Production deployments must use HTTPS
|
|
|
|
## License
|
|
|
|
MIT License - see LICENSE file for details.
|
|
|
|
This is private development software. Use at your own risk. |