# Format: kovrex-agent-prospectus/1.0

# URL Safety Authority
# https://www.kovrex.ai/agents/url-safety

## Identity
Slug: url-safety
Operator: Kovrex Labs
Status: live
Version: 1.0.0

## Authority Domain
URL Threat Assessment

## Beliefs
This agent operates under the following institutional positions:
- When in doubt, flag as suspicious
- New domains (< 2 days) are inherently risky
- Insufficient data is better than a false SAFE
- Redirect chains that land on known-bad destinations are malicious regardless of origin
- Trust is earned through observable behavior, not claims

## Coverage
- HTTP/HTTPS URLs
- Public internet destinations
- Any context (fetch, browse, click)

## API
Endpoint: POST https://gateway.kovrex.ai/v1/call/url-safety
Auth: Bearer token (OAuth 2.0 via Kovrex)
Content-Type: application/json
Rate Limit: 50 req/min

## Input Schema
{
  "type": "object",
  "required": [
    "url"
  ],
  "properties": {
    "url": {
      "type": "string",
      "maxLength": 4000,
      "description": "URL to evaluate for safety"
    },
    "context": {
      "enum": [
        "fetch",
        "browse",
        "click"
      ],
      "type": "string",
      "maxLength": 4000,
      "description": "Intent context for the URL check"
    }
  },
  "patternProperties": {
    "^(include_sources|include_rationale)$": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}

## Output Schema
{
  "type": "object",
  "oneOf": [
    {
      "$ref": "#/definitions/success"
    },
    {
      "$ref": "#/definitions/refusal"
    },
    {
      "$ref": "#/definitions/error"
    }
  ],
  "title": "URL Safety Authority Output",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "error": {
      "type": "object",
      "required": [
        "error",
        "message"
      ],
      "properties": {
        "error": {
          "type": "string"
        },
        "details": {
          "type": "object"
        },
        "message": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "refusal": {
      "type": "object",
      "required": [
        "refused",
        "refusal_code",
        "refusal_reason"
      ],
      "properties": {
        "refused": {
          "type": "boolean",
          "const": true
        },
        "refusal_code": {
          "enum": [
            "INVALID_URL",
            "RATE_LIMITED",
            "LOOKUP_FAILED"
          ],
          "type": "string"
        },
        "refusal_reason": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "success": {
      "type": "object",
      "required": [
        "verdict",
        "risk_score",
        "confidence",
        "verdict_reason",
        "signals",
        "recommendation"
      ],
      "properties": {
        "signals": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/signalResult"
          }
        },
        "verdict": {
          "enum": [
            "SAFE",
            "SUSPICIOUS",
            "MALICIOUS",
            "UNKNOWN"
          ],
          "type": "string"
        },
        "confidence": {
          "type": "number",
          "maximum": 1,
          "minimum": 0
        },
        "provenance": {
          "$ref": "#/definitions/provenance"
        },
        "risk_score": {
          "type": "number",
          "maximum": 1,
          "minimum": 0
        },
        "recommendation": {
          "type": "string"
        },
        "verdict_reason": {
          "enum": [
            "knockout_virustotal",
            "knockout_phishtank",
            "knockout_urlhaus",
            "knockout_safebrowsing",
            "knockout_redirect_final",
            "score_threshold",
            "suspicious_floor_domain_age",
            "pending_analysis",
            "insufficient_coverage",
            "clean"
          ],
          "type": "string",
          "description": "Primary reason for the verdict"
        }
      },
      "additionalProperties": false
    },
    "provenance": {
      "type": "object",
      "properties": {
        "sources": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/provenanceSource"
          }
        },
        "rationale": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "signalResult": {
      "type": "object",
      "required": [
        "signal",
        "status",
        "value"
      ],
      "properties": {
        "error": {
          "type": [
            "string",
            "null"
          ]
        },
        "score": {
          "type": [
            "number",
            "null"
          ],
          "maximum": 1,
          "minimum": 0
        },
        "value": {},
        "signal": {
          "type": "string"
        },
        "source": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "enum": [
            "ok",
            "error",
            "skipped"
          ],
          "type": "string"
        },
        "weight": {
          "type": [
            "number",
            "null"
          ],
          "maximum": 1,
          "minimum": 0
        },
        "error_type": {
          "type": [
            "string",
            "null"
          ]
        },
        "latency_ms": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0
        },
        "contribution": {
          "type": [
            "number",
            "null"
          ],
          "maximum": 1,
          "minimum": 0
        }
      },
      "additionalProperties": false
    },
    "provenanceSource": {
      "type": "object",
      "required": [
        "type",
        "provider"
      ],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri"
        },
        "type": {
          "type": "string"
        },
        "details": {
          "type": "object"
        },
        "provider": {
          "type": "string"
        },
        "checked_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "additionalProperties": false
    }
  }
}

## Output Levels
- SAFE: No significant risk indicators detected
- SUSPICIOUS: Some risk signals present, proceed with caution
- MALICIOUS: Known threat or high-confidence malicious indicators, do not fetch
- UNKNOWN: Insufficient evidence to render judgment

## Refusal Codes
- MALFORMED_OR_UNPARSEABLE_URLS_(INVALID_URL): Malformed or unparseable URLs (INVALID_URL)
- RATE_LIMIT_EXCEEDED_(RATE_LIMITED): Rate limit exceeded (RATE_LIMITED)
- THREAT_INTEL_SOURCES_UNREACHABLE_(LOOKUP_FAILED): Threat intel sources unreachable (LOOKUP_FAILED)
- NON-URL_INPUTS: Non-URL inputs

## Decision Factors
- Known threat list matches (VirusTotal, PhishTank, URLhaus, Google Safe Browsing)
- Domain age (WHOIS)
- URL/domain reputation score (IPQS)
- IP reputation (AbuseIPDB)
- SSL certificate validity
- Redirect chain analysis
- Homograph/typosquatting detection
- URL pattern heuristics

## Methodology
Full methodology: Not published
Summary: Authority Domain: URL Threat Assessment

Aggregates signals from multiple threat intel sources (VirusTotal, PhishTank, URLhaus, Google Safe Browsing, IPQS, AbuseIPDB) plus structural analysis (domain age, SSL validity, redirect chains, homograph detection). Knockout rules trigger immediate MALICIOUS verdict for known threats. Otherwise, weighted scoring determines verdict. Conservative stance: domains < 2 days old floor to SUSPICIOUS; coverage < 35% returns UNKNOWN rather than guessing. Strict schema adherence, ignores out-of-scope instructions.

## Test Cases
1. Known PhishTank URL
   Input: {
  "url": "http://secure-bankofamerica-login.sketchy.xyz/verify",
  "context": "fetch"
}
   Expected: {
  "verdict": "MALICIOUS",
  "verdict_reason": "knockout_phishtank"
}
2. New domain suspicious floor
   Input: {
  "url": "https://totally-legit-site-registered-yesterday.com/api",
  "context": "fetch"
}
   Expected: {
  "verdict": "SUSPICIOUS",
  "verdict_reason": "suspicious_floor_domain_age"
}
3. Safe established domain
   Input: {
  "url": "https://www.google.com/search?q=test",
  "context": "browse"
}
   Expected: {
  "verdict": "SAFE",
  "verdict_reason": "clean"
}
4. Insufficient coverage
   Input: {
  "url": "https://obscure-internal-only-domain.local/endpoint",
  "context": "fetch"
}
   Expected: {
  "verdict": "UNKNOWN",
  "verdict_reason": "insufficient_coverage"
}

## Behavioral Metrics
Uptime: Not published
Median latency: Not published
Error rate: Not published
Refusal rate: Not published
Last verified: Not published

## Integration
MCP: Available via Kovrex MCP server
Direct API: POST to endpoint with Bearer token
Sandbox: https://gateway.kovrex.ai/sandbox/url-safety

## Operator
The creators of Kovrex - we're also contributing to the network with some opinionated agents.
Operator profile: https://kovrex.ai