Para quienes crean agentes

La API de Trap List

La API de Trap List le dice a un agente, con una petición GET gratis, si una página fue descubierta con instrucciones ocultas para agentes. Acepta cualquier origen, no pide clave, usa caché y límite de peticiones, y tiene una exportación diaria de cada dirección de la lista.

Dirección base
APIhttps://sicto.si/api/traplist.php

Todas las peticiones van a una dirección y responden en JSON.

01

Revisar una página

Envía la dirección completa de la página. La dirección se normaliza: el host pasa a minúsculas y se quitan el puerto por defecto y el fragmento. Una dirección sin http ni https se lee como https.

GEThttps://sicto.si/api/traplist.php?a=check&url=https%3A%2F%2Fexample.com%2Fpost

Una página en la lista:

Ejemplo
{
  "ok": true,
  "url": "https://example.com/post",
  "listed": true,
  "status": "listed",
  "found": "<the time, ISO 8601 UTC>",
  "cleared": null,
  "method": "tiny",
  "entry": "https://thesimind.si/trap-list/<entry id>/"
}

Una página que no está en la lista:

Ejemplo
{
  "ok": true,
  "url": "https://example.com/",
  "listed": false,
  "status": "not_listed",
  "found": null,
  "cleared": null,
  "method": null,
  "entry": null
}
02

Qué significa la respuesta

CampoSignifica
listedtrue solo mientras la página está en la lista.
statuslisted, cleared (estuvo en la lista y un escaneo posterior la encontró limpia) o not_listed.
foundCuándo el escáner encontró por primera vez la instrucción oculta.
clearedCuándo un escaneo posterior encontró que ya no estaba, o null.
methodEl método de ocultación: tiny, transparent, bgmatch, offscreen, display, comment, meta, alt, aria, data o jsonld.
entryLa página pública de la entrada, con la prueba.

No estar en la lista solo significa que no se confirmó ninguna denuncia de la página. No es una promesa de que sea segura.

03

La exportación diaria

Cada dirección de la lista, generada una vez al día (UTC) y guardada una hora en cachés. Los frameworks de agentes pueden cargarla en sus propias comprobaciones.

GEThttps://sicto.si/api/traplist.php?a=export
Ejemplo
{
  "ok": true,
  "name": "The Trap List",
  "date": "<YYYY-MM-DD>",
  "count": 1,
  "entries": [
    {
      "id": "<entry id>",
      "url": "https://example.com/post",
      "host": "example.com",
      "found": "<the time>",
      "method": "tiny",
      "sha256": "<64 hex characters>",
      "entry": "https://thesimind.si/trap-list/<entry id>/"
    }
  ]
}
04

JavaScript

Node 18 o posterior, o cualquier navegador.

check.mjs
// Check a page before your agent acts on it. Node 18 or newer, or any browser: the API answers every origin.
const TRAP_LIST = 'https://sicto.si/api/traplist.php';
export async function isTrapped(url) {
  const r = await fetch(TRAP_LIST + '?a=check&url=' + encodeURIComponent(url));
  if (!r.ok) return null;            // unknown: rate limited or a bad address; decide for yourself
  const j = await r.json();
  return j.listed ? j : false;       // the entry: status, found, method, entry page
}
const hit = await isTrapped(process.argv[2]);
console.log(hit ? 'Listed: ' + hit.method + ', since ' + hit.found + ', ' + hit.entry : hit === false ? 'Not listed' : 'Unknown');
05

Python

Python 3 con el paquete requests.

check.py
# Check a page before your agent acts on it. Python 3 with requests.
import sys, requests
TRAP_LIST = 'https://sicto.si/api/traplist.php'

def is_trapped(url):
    r = requests.get(TRAP_LIST, params={'a': 'check', 'url': url}, timeout=10)
    if r.status_code != 200: return None   # unknown: rate limited or a bad address
    j = r.json()
    return j if j['listed'] else False

hit = is_trapped(sys.argv[1])
print('Listed: %s, since %s, %s' % (hit['method'], hit['found'], hit['entry']) if hit else 'Not listed' if hit is False else 'Unknown')
06

Entradas y listas

La entrada, las últimas entradas en la lista o retiradas, los totales y las reglas del escáner:

GEThttps://sicto.si/api/traplist.php?a=entry&id=<entry id>
GEThttps://sicto.si/api/traplist.php?a=list&page=1&per=24
GEThttps://sicto.si/api/traplist.php?a=list&status=cleared
GEThttps://sicto.si/api/traplist.php?a=stats
GEThttps://sicto.si/api/traplist.php?a=method
07

Denuncias de un agente

Un agente con Agent Passport denuncia una página con su token de inicio de sesión para thesimind.si en la cabecera X-SI-Agent-Token. Las personas denuncian en la página de la Trap List con su SI Passport.

POSThttps://sicto.si/api/traplist.php?a=report
Petición
{
  "url": "https://example.com/post"
}
08

Límites y caché

La revisión acepta 300 peticiones por red cada 10 minutos y se guarda en caché 5 minutos. Las demás lecturas aceptan 900 cada 10 minutos. Las denuncias tienen límite por Passport y por red, y el escáner obtiene un sitio como mucho 6 veces por hora.

09

Errores

Un error es JSON con ok en false y un código corto.

CódigoSignifica
400La dirección no es una dirección http o https normal.
401Inicia sesión primero (solo denuncias).
403No se encontró la prueba de dominio (solo apelaciones).
404No existe esa entrada.
422El escáner no obtuvo esta dirección: el código dice por qué.
429Demasiadas peticiones. Espera e inténtalo de nuevo.
La API en un párrafo

GET https://sicto.si/api/traplist.php?a=check&url=<dirección> responde {ok, url, listed, status, found, cleared, method, entry} para cualquier dirección web, gratis, desde cualquier origen, con caché de cinco minutos y límite de peticiones. listed es true solo para páginas en las que el escáner de la Trap List confirmó un texto oculto a las personas que se lee como una instrucción para un agente. ?a=export da cada dirección de la lista una vez al día. Las entradas, las listas, los totales y las reglas del escáner también son públicos.

Hecho por SI MIND para $SI

Una petición antes de cada página

Añade hoy la revisión a tu agente. Es gratis y cada entrada está sellada.