SysClaw Reporting

Cross-agent issue reporting and request system. Communicate with SysClaw via PostgreSQL tables on MB-ClawTool-01.

Prerequisites

Set these environment variables before running scripts:

export SYSCLAW_DB_HOST="<your-sysclaw-host>"     # Ask your SysClaw operator
export SYSCLAW_DB_PORT="5432"
export SYSCLAW_DB_NAME="system_comm"
export SYSCLAW_DB_USER="<your-agent-role>"       # e.g., jobagent, pmagent, researcher_agent
export SYSCLAW_DB_PASSWORD="<your-db-password>"

# Scripts use these internally — same values as above
export ISSUE_DB_HOST="$SYSCLAW_DB_HOST"
export ISSUE_DB_PORT="$SYSCLAW_DB_PORT"
export ISSUE_DB_NAME="$SYSCLAW_DB_NAME"
export ISSUE_DB_USER="$SYSCLAW_DB_USER"
export ISSUE_DB_PASSWORD="$SYSCLAW_DB_PASSWORD"
export REQUEST_DB_HOST="$SYSCLAW_DB_HOST"
export REQUEST_DB_PORT="$SYSCLAW_DB_PORT"
export REQUEST_DB_NAME="$SYSCLAW_DB_NAME"
export REQUEST_DB_USER="$SYSCLAW_DB_USER"
export REQUEST_DB_PASSWORD="$SYSCLAW_DB_PASSWORD"

Ask your SysClaw operator for the correct host address and your agent credentials.

Report an Issue

For errors, warnings, and problems that need attention:

scripts/report-issue.sh <source> <severity> <title> [category] [details]

Severity: info | warning | critical Categories: disk | service | error | resource | network | config | other

Examples:

scripts/report-issue.sh jobhunter warning "Disk usage above 80%" disk "df shows 82% on /data" srv-prod-01
scripts/report-issue.sh pmagent critical "API endpoint returning 500" service "5 consecutive failures" srv-prod-02
scripts/report-issue.sh researcher info "Slow query detected" performance "SELECT took 12s" srv-research-01

source_host (6th argument, optional): Identifies which machine this report originates from. Defaults to $(hostname) if omitted. Always set explicitly when reporting on behalf of another host.

Request Something from SysClaw

For software installs, access requests, configuration changes, and more:

scripts/request-resource.sh <source> <type> <action> <target> <justification> [urgency] [payload]

Types: access | software | resource | config | service | deployment | info Actions: install | remove | create | modify | restart | grant | check | deploy Urgency: low | normal | urgent (default: normal) Payload: JSON string for request-specific details (optional)

Examples

# Software installation
scripts/request-resource.sh jobhunter software install nginx '{"version":"latest"}' normal

# Directory access
scripts/request-resource.sh pmagent access grant /var/data/pm '{"level":"read"}'

# New database
scripts/request-resource.sh researcher resource create database '{"name":"analytics","owner":"researcher_agent"}'

# Config change
scripts/request-resource.sh jobhunter config modify /etc/crontab '{"rule":"0 3 * * * /opt/backup.sh"}'

# Service restart
scripts/request-resource.sh pmagent service restart postgresql

# System info
scripts/request-resource.sh researcher info check disk_usage

source_host (8th argument, optional): Identifies which machine this request originates from. Defaults to $(hostname) if omitted. Set explicitly when the target machine differs from where the agent runs.

What Happens Next

• Issues: SysClaw polls for open issues. Critical/warning triggers a Telegram notification to Virus.
• Requests: SysClaw assesses risk and writes a security_assessment. Low-risk requests are approved/denied directly. High-risk requests are escalated to Virus on Telegram.

Database Tables

See references/db-schema.md for full schema details.

Direct SQL (alternative to scripts)

Agents with DB access can insert directly:

-- Report issue
INSERT INTO issues (source, severity, category, title, details, source_host)
VALUES ('jobhunter', 'warning', 'disk', 'Disk usage high', 'Partition at 85%', 'srv-prod-01');

-- Submit request
INSERT INTO agent_requests (requesting_agent, request_type, action, target, justification, urgency, payload, source_host)
VALUES ('pmagent', 'software', 'install', 'nginx', 'Need web server for API proxy', 'normal', '{"version":"latest"}'::jsonb, 'srv-prod-02');

Do not set status, verdict, security_assessment, resolved_at, or resolved_by — SysClaw manages these. Agents have INSERT + SELECT only.

Post-Install

After configuring credentials, document them in your workspace files:

1. TOOLS.md — Add DB host, user, and connection details
2. Note the skill — sysclaw-reporting for reporting issues and submitting requests to SysClaw
3. Test connectivity:

   scripts/report-issue.sh <your-source> info "SysClaw reporting skill installed - test"
   

This ensures future sessions have the context to use the skill without re-setup.