So lösen Sie Captchas in Activepieces (HTTP-Piece)

Ein Captcha-Solve in Activepieces besteht aus drei Schritten: die Challenge übermitteln, warten, das Token auslesen. Bauen Sie ihn auf dem HTTP-Piece statt auf einem Code-Step, denn ob ein Code-Step überhaupt npm nutzen kann, hängt davon ab, in welchem Sandbox-Modus Ihre Instanz läuft, und der Modus, den Activepieces Cloud verwendet, hat kein npm. Das HTTP-Piece funktioniert in jedem Modus. Es gibt eine zweite Einstellung, die wichtiger ist als der Code, und sie entscheidet, ob Ihr Flow einen Löser auf einer privaten Adresse überhaupt erreichen kann.

Was Sie brauchen

• Ein Activepieces-Projekt, in dem Sie einen Flow veröffentlichen können, in deren Cloud oder selbst gehostet.
• CapSkip, das auf einem Windows-Rechner läuft. Der Local-Modus reicht nur, wenn Activepieces auf demselben Rechner läuft, was in der Praxis eine selbst gehostete Installation bedeutet. Alles andere braucht den Server-Modus.
• Der sitekey und die Seiten-URL der Website, die Sie automatisieren.
• Eine Projektvariable, die den Schlüssel des Lösers enthält, damit er nicht im Flow selbst steht.
• Auf einer selbst gehosteten Instanz mit gehärtetem Netzwerk: ein Eintrag in der SSRF-Allow-List. Schritt 3 behandelt das.

Warum das HTTP-Piece und nicht ein Code-Step

Der Editor für Code-Steps hat einen Dialog Add npm package. Er schlägt das Paket in der npm-Registry nach, pinnt die neueste Version und trägt sie in die Abhängigkeitsliste des Steps ein. In Activepieces Cloud wird diese Liste anschließend verworfen.

Activepieces baut einen Code-Step, indem es Ihren Quelltext in eine TypeScript-Datei schreibt, dessen Abhängigkeiten installiert und das Ergebnis bündelt. Der Build fragt Ihre Abhängigkeiten nur dann ab, wenn der Ausführungsmodus der Instanz Pakete zulässt. Beim V8-Sandboxing, dem Modus, den Activepieces als den in der eigenen Cloud laufenden dokumentiert, sind Pakete nicht erlaubt, also setzt der Build eine leere Abhängigkeitsmenge ein und kompiliert trotzdem. Der Step wird sauber deployt. Der Import scheitert erst, wenn der Flow läuft.

Es gibt also zwei ehrliche Wege dorthin, und welchen Sie bekommen, ist nicht Ihre Entscheidung, sondern die Ihres Administrators. Der Weg über das HTTP-Piece weiter unten funktioniert in allen vier Modi. Der Weg über den Code-Step am Ende dieser Anleitung funktioniert in zweien davon und ist deutlich kürzer, wenn Sie ihn haben.

Schritt 1: die Challenge übermitteln

CapSkip spricht die 2captcha-kompatible API auf Port 8080, sodass das HTTP-Piece ohne zu installierenden Connector mit ihm redet. Fügen Sie eine Send HTTP Request-Aktion hinzu, setzen Sie die Methode auf POST und die URL auf den Submit-Endpunkt Ihres Lösers.

{
  "key": "{{variables['CAPSKIP_KEY']}}",
  "method": "userrecaptcha",
  "googlekey": "YOUR_SITEKEY",
  "pageurl": "https://example.com/page-with-recaptcha",
  "json": 1
}

Die Antwort ist ein kleines JSON-Objekt, dessen Feld request die ID enthält, mit der Sie abfragen.

{ "status": 1, "request": "2122988149" }

Das war reCAPTCHA v2. Die anderen Typen, die CapSkip unterstützt, sind derselbe Aufruf mit anderen Parametern: invisible oder enterprise auf 1 setzen, oder version auf v3 mit einem action-Namen, oder method auf turnstile beziehungsweise geetest umstellen. Die vollständige Parameterliste steht in der CapSkip-API-Dokumentation.

Referenzieren Sie den Schlüssel mit der Syntax für Projektvariablen, statt ihn einzufügen. Variablen sind im Ruhezustand verschlüsselt und werden Ihnen in der Variablenliste nie wieder angezeigt, und ein Wechsel des Schlüssels ist eine einzige Änderung statt einer Suche durch jeden Flow.

Schritt 2: warten, dann das Token auslesen

Fügen Sie eine Delay For-Aktion hinzu und danach eine zweite HTTP-Anfrage, die das Ergebnis ausliest. Zwanzig Sekunden sind eine sinnvolle erste Wartezeit für eine reCAPTCHA-v2-Checkbox. Bild-Captchas kommen in etwa einer Sekunde zurück, v3 in zehn bis fünfzehn, GeeTest in etwa fünf.

# GET, with the id from step 1 in the query string.
http://127.0.0.1:8080/res.php?key=YOUR_KEY&action=get&id=2122988149&json=1

Zwei Antworten sind möglich. Ein fertiges Ergebnis ist ein JSON-Objekt in der Form der Submit-Antwort, mit dem Token im Feld request. Ein noch nicht fertiges Ergebnis ist die Zeichenkette CAPCHA_NOT_READY, geschrieben ohne T, und sie bedeutet weiter warten und nicht etwa, dass etwas schiefgegangen ist. Die Geschichte dieser Schreibweise steht in der ausführlichen Aufarbeitung der CAPCHA_NOT_READY-Antwort.

Das Delay-Piece verhält sich dies- und jenseits der Zehn-Sekunden-Grenze unterschiedlich, und genau dieses Detail macht die Polling-Form hier so günstig. Eine Verzögerung von zehn Sekunden oder weniger schläft im Worker-Prozess. Alles darüber erzeugt einen Waitpoint, hält den Lauf an und setzt ihn fort, wenn die Zeit abgelaufen ist. Angehaltene Zeit ist keine Ausführungszeit, und Activepieces dokumentiert, dass Flows, die durch Delay oder durch Wait for Approval pausiert sind, nicht auf das Run-Timeout angerechnet werden. Eine Wartezeit von zwanzig Sekunden kostet Sie also nichts von Ihrem Budget von zehn Minuten, und eine zweite ebenso wenig.

Wenn ein Lesevorgang nicht reicht, fügen Sie ein weiteres Delay und einen weiteren Lesevorgang hinzu, statt zu einer Schleife zu greifen. Zwei Gründe. Ein Loop on Items durchläuft jedes Element der Liste, die Iterationen finden also statt, ob das Token schon da ist oder nicht, und ein Router darin erspart Ihnen die Arbeit im Zweig, nicht den Durchlauf der Schleife. Wichtiger noch: Ein CapSkip-Ergebnis ist nur einmal lesbar, eine Schleife, die eine bereits abgeholte ID erneut liest, bekommt das Token also nicht zweimal, sondern beim zweiten Lesen einen Fehler.

Schritt 3: die Netzwerkeinstellung, die einen lokalen Löser blockiert

Das ist der Teil, über den Leute stolpern, und er ist spezifisch für Activepieces, kein allgemeiner Orchestrator-Ratschlag. Activepieces hat einen SSRF-Schutz für Flow-Code, gesteuert über eine Variable namens AP_NETWORK_MODE. Der Standardwert ist UNRESTRICTED. Auf STRICT gesetzt, patcht die Engine den DNS-Lookup und den Socket-Connect von Node, bevor irgendein Flow-Code läuft, und verweigert jede Verbindung, deren Adresse Loopback, RFC1918-privat, Link-local oder Cloud-Metadaten ist. Sie wirft einen Fehler namens SSRFBlockedError.

Ein Captcha-Löser im eigenen Netzwerk ist genau das Muster, das dieser Schutz blockiert. Sowohl 127.0.0.1 als auch eine LAN-Adresse wie 192.168.1.40 stehen auf der Liste. Das ist der Schutz, der seine Arbeit tut, kein Fehler, und Activepieces gibt Ihnen die dokumentierte Ausnahme dafür: Tragen Sie die Adresse des Lösers in AP_SSRF_ALLOW_LIST ein, die kommagetrennte IPs und CIDR-Bereiche annimmt und für Flow-Code ebenso gilt wie für die ausgehenden Anfragen des Servers selbst. Starten Sie den Server nach der Änderung neu.

# On a self-hosted Activepieces with AP_NETWORK_MODE=STRICT,
# name the solver machine or its subnet so flows can reach it.
AP_SSRF_ALLOW_LIST=192.168.1.40,10.0.5.0/24

Unabhängig von diesem Schutz muss der Flow den Rechner überhaupt erreichen können. CapSkip hat dafür zwei Verbindungsmodi. Der Local-Modus bindet an 127.0.0.1 und bedient nur dieses Gerät. Der Server-Modus bindet an Ihre Netzwerkadresse oder öffentliche IP, sodass ein anderer Rechner, ein Container-Host oder eine gehostete Plattform denselben Windows-Rechner über die API erreichen kann. Beide finden Sie unter Verbindungseinstellungen, und der Server-Modus ändert nur, auf welcher Adresse der Löser lauscht. Es ist weiterhin Ihre Hardware, und es wird weiterhin nicht pro Lösung abgerechnet.

Schritt 4: Timeouts und Wiederholungen

Drei Zahlen entscheiden, ob eine langsame Lösung durchkommt, und nur eine davon setzen Sie selbst im Flow.

Die Webhook-Zahl ist die, die zubeißt. Eine Webhook-URL, die auf das Wort sync endet, hält die HTTP-Verbindung offen und antwortet mit dem Ergebnis des Flows, und sie gibt nach dreißig Sekunden auf. Eine reCAPTCHA-v2-Lösung ist nicht zuverlässig innerhalb von dreißig Sekunden fertig, also bekommt ein Aufrufer, der den Flow synchron auslöst und ein Token zurückerwartet, HTTP 408, während der Flow dahinter weiterläuft. Lösen Sie den Flow asynchron aus und lassen Sie ihn das Token dorthin schicken, wo Sie es brauchen, oder teilen Sie die Arbeit so auf, dass die synchrone Hälfte nie auf eine Lösung wartet.

Retry on Failure lohnt sich für den Submit-Step und nicht für den Read-Step. Sein Backoff ist exponentiell ab einer Basis von zwei Sekunden, die Wartezeiten liegen über vier Versuche also bei rund vier, acht und sechzehn Sekunden. Das ist richtig für eine abgewiesene Verbindung. Es ist falsch für ein Token, das Sie bereits abgeholt haben, wegen der oben genannten Regel, dass sich ein Ergebnis nur einmal lesen lässt.

Das Ganze in einem Step, auf einer selbst gehosteten Instanz

Wenn Ihr Administrator kein Sandboxing oder Kernel-Namespace-Sandboxing betreibt, schrumpft der Flow oben auf einen einzigen Code-Step, weil das SDK das Polling für Sie übernimmt. Fügen Sie capskip im npm-Dialog hinzu und schreiben Sie dann den Step. Code-Steps sind TypeScript und werden vor der Ausführung gebündelt, ein gewöhnlicher Import funktioniert also.

// npm install capskip - add it in the step's package dialog.
import { CapSkip } from 'capskip';

export const code = async (inputs) => {
  // host is the solver machine. Keep 127.0.0.1 only when
  // Activepieces runs on the same Windows box as CapSkip.
  const solver = new CapSkip({
    host: inputs.capskipHost,
    port: 8080,
    apiKey: inputs.capskipKey,
  });

  const result = await solver.recaptcha(inputs.sitekey, inputs.pageUrl);

  // Return the token, not the whole result. The next step
  // submits it, and run logs keep whatever you return.
  return { token: result.code };
};

Übergeben Sie capskipKey als Step-Input, der die Referenz auf die Projektvariable enthält, damit der Schlüssel zur Laufzeit aufgelöst wird und nie im Quelltext auftaucht. Das SDK beginnt das Polling bei 250 Millisekunden und vergrößert den Abstand, statt in einem festen Intervall zu schlafen, weshalb diese Variante meist schneller zurückkommt als der Flow mit Delay. Seine Obergrenze für reCAPTCHA, Turnstile und GeeTest liegt bei 300 Sekunden, deutlich innerhalb des Aktions-Timeouts von zehn Minuten.

Übermitteln Sie das Token im unmittelbar folgenden Step. Ein reCAPTCHA-Token ist etwa zwei Minuten lang gültig, ein Flow, der löst, an einem Approval-Step wartet und dann übermittelt, scheitert also an einem Token, das bei seiner Erzeugung völlig gültig war. Dieser Fehlerfall wird behandelt in der Anleitung zu Gültigkeitsdauer von reCAPTCHA-Token.

Häufige Fehler und was sie bedeuten

FAQ

Die Kurzfassung

Bauen Sie die Lösung auf dem HTTP-Piece, weil es in jedem Sandbox-Modus funktioniert und der Weg über den Code-Step nicht. Senden Sie an den Submit-Endpunkt, warten Sie länger als zehn Sekunden, damit der Lauf angehalten wird, statt einen Worker zu belegen, und lesen Sie das Ergebnis dann einmal aus und behalten Sie es. Legen Sie den Schlüssel in eine Projektvariable. Ist die Instanz selbst gehostet und der Netzwerkmodus strikt, tragen Sie den Löser in die SSRF-Allow-List ein, und wenn Activepieces irgendwo anders läuft als auf dem Rechner des Lösers, stellen Sie CapSkip auf den Server-Modus um. Warten Sie nie an einem synchronen Webhook auf eine Lösung.

• Die reCAPTCHA-v2-Checkbox selbst wird behandelt auf die reCAPTCHA-v2-Solver-Seite.
• Die entsprechenden Varianten mit einem einzigen Aufruf in Python, Node.js, PHP und C# sind aufgeführt auf Die Seite zu den SDKs fürs Captcha-Lösen.

Eines sollten Sie abwägen, bevor Sie diesen Flow alle paar Minuten einplanen: CapSkip ist ein unbegrenzter Captcha-Löser der auf Hardware läuft, die Ihnen bereits gehört, ein Flow, der ständig feuert, kostet also genau dasselbe wie einer, der nur gelegentlich feuert.