214 lines
6.4 KiB
Markdown
214 lines
6.4 KiB
Markdown
---
|
|
title: Agentic Client
|
|
description: Security scanning, metrics recording, and CLI command integrations.
|
|
---
|
|
|
|
# Agentic Client
|
|
|
|
go-ai provides several CLI command packages that integrate AI-adjacent functionality into the `core` binary. These cover security scanning across multi-repo environments, AI metrics viewing, and homelab monitoring.
|
|
|
|
## Security Scanning
|
|
|
|
The `cmd/security/` package provides a comprehensive security scanning suite that queries GitHub's security APIs across repositories defined in a `repos.yaml` registry.
|
|
|
|
### Command Structure
|
|
|
|
```
|
|
core security
|
|
+-- alerts # Unified view of all security alert types
|
|
+-- deps # Dependabot dependency vulnerability alerts
|
|
+-- scan # Code scanning alerts (CodeQL, etc.)
|
|
+-- secrets # Secret scanning alerts
|
|
+-- jobs # Create GitHub issues from scan findings
|
|
```
|
|
|
|
### Common Flags
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `--registry` | Path to `repos.yaml` (auto-detected if omitted) |
|
|
| `--repo` | Filter to a single repository |
|
|
| `--severity` | Filter by severity: `critical`, `high`, `medium`, `low` (comma-separated) |
|
|
| `--json` | Output as JSON instead of formatted table |
|
|
| `--target` | External repo target (e.g. `wailsapp/wails`) -- bypasses registry |
|
|
|
|
### Alerts
|
|
|
|
The `alerts` command provides a unified view combining Dependabot, code scanning, and secret scanning alerts:
|
|
|
|
```bash
|
|
core security alerts # All repos in registry
|
|
core security alerts --repo core-php # Single repo
|
|
core security alerts --severity critical,high # Filter by severity
|
|
core security alerts --target wailsapp/wails # External repo
|
|
core security alerts --json # JSON output
|
|
```
|
|
|
|
### Dependencies
|
|
|
|
Query Dependabot vulnerability alerts with upgrade suggestions:
|
|
|
|
```bash
|
|
core security deps
|
|
core security deps --severity high
|
|
```
|
|
|
|
Output includes the vulnerable version range and the first patched version when available.
|
|
|
|
### Code Scanning
|
|
|
|
Query code scanning alerts from tools like CodeQL:
|
|
|
|
```bash
|
|
core security scan
|
|
core security scan --tool codeql # Filter by scanning tool
|
|
```
|
|
|
|
Each scan execution records a metrics event via `ai.Record()` for tracking scan activity over time.
|
|
|
|
### Secret Scanning
|
|
|
|
Check for exposed secrets across repositories:
|
|
|
|
```bash
|
|
core security secrets
|
|
core security secrets --json
|
|
```
|
|
|
|
Secrets are always treated as high severity. The output flags whether push protection was bypassed.
|
|
|
|
### Jobs
|
|
|
|
Create GitHub issues from security findings for agent-driven remediation:
|
|
|
|
```bash
|
|
core security jobs --targets wailsapp/wails
|
|
core security jobs --targets wailsapp/wails --issue-repo host-uk/core
|
|
core security jobs --targets wailsapp/wails --dry-run
|
|
core security jobs --targets a/b,c/d --copies 3
|
|
```
|
|
|
|
| Flag | Default | Description |
|
|
|------|---------|-------------|
|
|
| `--targets` | (required) | Comma-separated `owner/repo` targets |
|
|
| `--issue-repo` | `host-uk/core` | Repository where issues are created |
|
|
| `--dry-run` | `false` | Preview without creating issues |
|
|
| `--copies` | `1` | Number of issue copies per target |
|
|
|
|
Each created issue includes a findings summary, checklist, and instructions. A metrics event is recorded for each issue created.
|
|
|
|
## Metrics
|
|
|
|
The `ai/` package provides a JSONL-based metrics recording system. Events are stored at:
|
|
|
|
```
|
|
~/.core/ai/metrics/YYYY-MM-DD.jsonl
|
|
```
|
|
|
|
### Event Structure
|
|
|
|
```go
|
|
type Event struct {
|
|
Type string `json:"type"`
|
|
Timestamp time.Time `json:"timestamp"`
|
|
AgentID string `json:"agent_id,omitempty"`
|
|
Repo string `json:"repo,omitempty"`
|
|
Duration time.Duration `json:"duration,omitempty"`
|
|
Data map[string]any `json:"data,omitempty"`
|
|
}
|
|
```
|
|
|
|
### Recording Events
|
|
|
|
```go
|
|
ai.Record(ai.Event{
|
|
Type: "security.scan",
|
|
Timestamp: time.Now(),
|
|
Repo: "wailsapp/wails",
|
|
Data: map[string]any{
|
|
"total": summary.Total,
|
|
"critical": summary.Critical,
|
|
},
|
|
})
|
|
```
|
|
|
|
Writing uses `O_APPEND` with a mutex for concurrent safety. Missing directories are created automatically.
|
|
|
|
### Reading and Querying
|
|
|
|
```go
|
|
events, err := ai.ReadEvents(since) // Read events from a time range
|
|
summary := ai.Summary(events) // Aggregate by type, repo, agent
|
|
```
|
|
|
|
`ReadEvents` iterates calendar days from `since` to today, opening each daily file. Missing files are silently skipped. Malformed JSONL lines are skipped without error.
|
|
|
|
`Summary` returns a `map[string]any` with:
|
|
- `total` -- total event count
|
|
- `by_type` -- sorted slice of `{key, count}` maps
|
|
- `by_repo` -- sorted slice of `{key, count}` maps
|
|
- `by_agent` -- sorted slice of `{key, count}` maps
|
|
|
|
### CLI Command
|
|
|
|
```bash
|
|
core ai metrics # Last 7 days (default)
|
|
core ai metrics --since 30d # Last 30 days
|
|
core ai metrics --since 24h # Last 24 hours
|
|
core ai metrics --json # JSON output
|
|
```
|
|
|
|
Duration format: `Nd` (days), `Nh` (hours), `Nm` (minutes).
|
|
|
|
### MCP Tools
|
|
|
|
The metrics system is also exposed via two MCP tools:
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `metrics_record` | Record an event to the JSONL store |
|
|
| `metrics_query` | Query and summarise events for a time period |
|
|
|
|
## Lab Dashboard
|
|
|
|
The `cmd/lab/` package provides a homelab monitoring dashboard with real-time data collection:
|
|
|
|
```bash
|
|
core lab serve # Start on :8080
|
|
core lab serve --bind :9090 # Custom port
|
|
```
|
|
|
|
### Collectors
|
|
|
|
The dashboard aggregates data from multiple sources:
|
|
|
|
| Collector | Interval | Source |
|
|
|-----------|----------|--------|
|
|
| System | 60s | Local machine stats |
|
|
| Prometheus | Configurable | Prometheus endpoint |
|
|
| HuggingFace | Configurable | HF model metadata |
|
|
| Docker | Configurable | Docker container status |
|
|
| Forgejo | Configurable | Forge CI/CD status |
|
|
| Training | Configurable | ML training run status |
|
|
| Services | 60s | Service health checks |
|
|
| InfluxDB | Configurable | Time-series metrics |
|
|
|
|
### Routes
|
|
|
|
**Web pages:** `/`, `/models`, `/training`, `/dataset`, `/agents`, `/services`
|
|
|
|
**JSON API:** `/api/status`, `/api/models`, `/api/training`, `/api/dataset`, `/api/runs`, `/api/agents`, `/api/services`
|
|
|
|
**Live updates:** `/events` (Server-Sent Events)
|
|
|
|
**Health:** `/health`
|
|
|
|
## RAG CLI
|
|
|
|
The `cmd/rag/` package re-exports `go-rag`'s CLI commands for use within the `core` binary:
|
|
|
|
```go
|
|
var AddRAGSubcommands = ragcmd.AddRAGSubcommands
|
|
```
|
|
|
|
This makes RAG operations (ingest, query, collection management) available as `core rag` subcommands without duplicating the implementation.
|