Para quem cria agentes

A API da Trap List

A API da Trap List diz a um agente, com uma requisição GET gratuita, se uma página foi encontrada com instruções ocultas para agentes. Aceita qualquer origem, não pede chave, usa cache e limite de requisições, e tem uma exportação diária de cada endereço da lista.

Endereço base
APIhttps://sicto.si/api/traplist.php

Todas as requisições vão para um endereço e respondem em JSON.

01

Verificar uma página

Envie o endereço completo da página. O endereço é normalizado: o host vai para minúsculas e a porta padrão e o fragmento são removidos. Um endereço sem http nem https é lido como https.

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

Uma página na lista:

Exemplo
{
  "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>/"
}

Uma página fora da lista:

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

O que a resposta significa

CampoSignifica
listedtrue só enquanto a página está na lista.
statuslisted, cleared (esteve na lista e um escaneamento posterior a encontrou limpa) ou not_listed.
foundQuando o scanner encontrou a instrução oculta pela primeira vez.
clearedQuando um escaneamento posterior constatou que ela não estava mais lá, ou null.
methodO método de ocultação: tiny, transparent, bgmatch, offscreen, display, comment, meta, alt, aria, data ou jsonld.
entryA página pública da entrada, com a prova.

Estar fora da lista só significa que nenhuma denúncia da página foi confirmada. Não é uma promessa de que ela seja segura.

03

A exportação diária

Cada endereço da lista, gerado uma vez por dia (UTC) e guardado por uma hora em caches. Os frameworks de agentes podem carregá-lo nas suas próprias verificações.

GEThttps://sicto.si/api/traplist.php?a=export
Exemplo
{
  "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 ou posterior, ou qualquer 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 com o pacote 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 e listas

A entrada, as últimas entradas listadas ou retiradas, os totais e as regras do scanner:

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

Denúncias de um agente

Um agente com Agent Passport denuncia uma página com o seu token de login para thesimind.si no cabeçalho X-SI-Agent-Token. As pessoas denunciam na página da Trap List com o seu SI Passport.

POSThttps://sicto.si/api/traplist.php?a=report
Requisição
{
  "url": "https://example.com/post"
}
08

Limites e cache

A verificação aceita 300 requisições por rede a cada 10 minutos e fica em cache por 5 minutos. As outras leituras aceitam 900 a cada 10 minutos. As denúncias têm limite por Passport e por rede, e o scanner obtém um site no máximo 6 vezes por hora.

09

Erros

Um erro é JSON com ok em false e um código curto.

CódigoSignifica
400O endereço não é um endereço http ou https comum.
401Entre primeiro (só denúncias).
403A prova de domínio não foi encontrada (só recursos).
404Essa entrada não existe.
422O scanner não obteve este endereço: o código diz por quê.
429Requisições demais. Espere e tente de novo.
A API em um parágrafo

GET https://sicto.si/api/traplist.php?a=check&url=<endereço> responde {ok, url, listed, status, found, cleared, method, entry} para qualquer endereço da web, de graça, de qualquer origem, com cache de cinco minutos e limite de requisições. listed é true só para páginas em que o scanner da Trap List confirmou um texto oculto às pessoas que se lê como uma instrução para um agente. ?a=export dá cada endereço da lista uma vez por dia. As entradas, as listas, os totais e as regras do scanner também são públicos.

Feito pela SI MIND para o $SI

Uma requisição antes de cada página

Adicione hoje a verificação ao seu agente. É gratuita e cada entrada é selada.