가이드
이미 알고 있는 URL을 제한된 escalation ladder로 읽습니다.
agbrowse fetch는 검색 명령이 아닙니다. 후보 URL 하나를 6단계 adaptive escalation ladder로 읽어 evidence를 반환합니다. 검색 도구나 사용자가 URL을 제공한 후 안전 점검과 함께 내용을 추출할 때 사용합니다.
기본 사용법
agbrowse fetch https://example.com --json
agbrowse fetch https://example.com --json --trace
agbrowse fetch https://example.com --selector main --max-bytes 60000
agbrowse fetch https://example.com --browser never
agbrowse fetch https://example.com --browser required
agbrowse fetch https://example.com --allow-third-party-reader
agbrowse fetch https://example.com --browser-session user
agbrowse fetch https://example.com --identity chromeEscalation ladder
fetcher는 단계를 순서대로 실행합니다. 각 단계 후 content scoring으로 추가 escalation 여부를 결정합니다.
| 단계 | Rung | 설명 |
|---|---|---|
| 1 | Public endpoint + HTTP fetch | 알려진 public API endpoint(GitHub, Reddit, HN, Wikipedia, npm, PyPI, arXiv, Bluesky, Mastodon, Stack Exchange, dev.to, DOI/CrossRef, OpenLibrary, Wayback CDX, YouTube/X oEmbed, HN Algolia, V2EX, Lobsters, generic oEmbed)를 resolve하고 브라우저급 identity 헤더로 직접 HTTP fetch합니다. |
| 2 | TLS-impersonation | 403/429/challenge 응답 시 curl-impersonate로 JA3/TLS 지문을 위장합니다(chrome131, safari18, firefox133 프로파일). DNS는 --resolve로 사전 resolve 후 고정하여 TOCTOU SSRF를 방지합니다. |
| 3 | Readers | 특화 reader를 시도합니다: yt-dlp로 미디어 메타데이터 및 자막 추출, RSS/Atom/JSON-feed 파서로 피드 URL 파싱, 서드파티 reader(Jina Reader, --allow-third-party-reader로 opt-in). |
| 4 | Camoufox stealth browser | 사용 가능할 때 Camoufox(강화된 Firefox, Python 기반 위장 지문)로 페이지를 렌더링합니다. python3 + camoufox 미설치 시 no-op. |
| 5 | Isolated Chrome render | CDP를 통해 샌드박스 Chrome을 실행하고, 페이지를 렌더링하고, Defuddle로 텍스트를 추출하고, network API JSON 후보를 탐색합니다. |
| 6 | User session / human-in-the-loop | --browser-session user로 인증된 브라우저 세션을 사용합니다. --browser-session interactive로 사람의 challenge 해결을 추가합니다. |
Escalation 제어
| Flag | 역할 |
|---|---|
--browser auto|never|required | 브라우저 escalation 제어. never는 HTTP/TLS/reader 단계에서 중단. |
--browser-session none|isolated|existing|user|interactive | 인증된 사용자 상태 허용 여부 선택. |
--identity auto|minimal|chrome | 요청 header identity 선택. chrome/auto는 브라우저급 헤더 전송, minimal은 Accept만 전송. |
--max-bytes N | 시도당 응답 크기 제한. |
--timeout-ms N | 시도당 타임아웃. |
--selector CSS | 브라우저 텍스트 추출 CSS selector. |
--allow-third-party-reader | Jina Reader 등 public reader opt-in. |
--no-public-endpoints | 알려진 public endpoint resolve 건너뛰기. |
--trace | 단계별 시도 trace를 출력에 포함. |
콘텐츠 처리
피드 파싱
가져온 콘텐츠가 RSS, Atom, 또는 JSON Feed 문서일 때 피드 파서가 구조화된 항목(제목, 날짜, 저자, 요약, 태그, 미디어 URL)을 추출하고 evidence로 포맷합니다. reader 단계에서 자동으로 실행됩니다.
구조화된 테이블/헤딩 추출
structured extractor는 가져온 HTML에서 headings, tables(캡션, 헤더, 행), ordered/unordered lists, code blocks, JSON-LD를 추출합니다. Defuddle의 산문 전용 추출을 보완하여 agent가 추론할 수 있는 그리드 데이터를 제공합니다.
BM25 lexical reranking
검색 쿼리가 있을 때 BM25 필터가 긴 문서를 쿼리와 가장 관련성 높은 top-K 문단으로 줄입니다(문서 순서 유지). tf-idf 스코어링을 사용하며 topK와 minScore 파라미터를 설정할 수 있습니다.
후보 URL 탐색
candidate discovery 모듈은 가져온 페이지 내 URL을 추출하고 랭킹합니다. 각 URL은 lane(official, package, academic, community, realtime, archive, fetch)으로 분류되며, SSRF 거부, 트래킹 파라미터 정규화, 중복 제거, lane 가중 스코어링이 적용됩니다. agbrowse search 파이프라인의 다중 URL evidence 수집에 활용됩니다.
WAF 프로파일 탐지
challenge detector는 응답 헤더, 쿠키, body 패턴, 상태 코드에서 WAF provider를 식별합니다. 인식되는 프로파일:
- Cloudflare – managed challenge + Turnstile
- Akamai – Bot Manager
- AWS WAF
- Imperva / Incapsula
- DataDome
- PerimeterX
탐지 결과는 escalation 결정(예: TLS-impersonation이나 stealth browser 성공 가능성)에 반영되고 시도 trace에 기록됩니다.
보안 대책
SSRF DNS 고정
모든 curl 기반 fetch(TLS-impersonation 포함)는 DNS를 사전 resolve하고 curl --resolve로 결과를 고정합니다. 이로써 검증과 연결 사이에 DNS 응답이 변경될 수 있는 TOCTOU 창을 닫아, 내부 네트워크 대상 DNS rebinding 공격을 방지합니다.
검증된 리다이렉트 루프
curl -L로 리다이렉트를 무조건 따르는 대신, 홉별 검증 리다이렉트 루프(최대 5홉)를 실행합니다. 각 리다이렉트 대상은 validateFetchUrl과 DNS rebinding guard를 다시 통과한 후에만 따르므로, 리다이렉트 체인이 사설 IP 공간으로 이탈할 수 없습니다.
멀티홉 헤더 파싱
리다이렉트 루프는 멀티홉 리다이렉트 후 curl의 effective URL에서 실제 finalUrl을 정확히 추출하여, 하류 evidence가 항상 실제 도달 페이지를 기록합니다.
출력
--json 모드에서 선택된 content 필드는 직렬화 전 크기가 제한되어 stdout이 파싱 가능하게 유지됩니다. 결과에 contentBytes, contentLimitBytes, contentTruncated 필드가 포함됩니다. truncation은 CLI 출력만 압축된 것이며 소스가 거부된 것이 아닙니다.
경계
fetcher는 WAF/auth/paywall signal을 감지하고 보고할 수 있지만, CAPTCHA 우회, 접근 제어 우회, 명시적 user-session 모드 없는 private credential 사용은 하지 않습니다. 자동화된 CAPTCHA 풀이, credential stuffing, stealth는 금지됩니다. 사람의 도움(브라우저급 헤더, user session, human resolve)은 명시적 opt-in flag로만 허용됩니다.