Konfigurácia
config/safe-fetch.php sú predvolené pravidlá pre Http::safe(), SafeFetch::vet(), SafeFetch::fetch() a pravidlo safe_url. Tabuľka blokovaných sietí platí vždy; tieto nastavenia k nej len pridávajú alebo z nej vynímajú. Publikujete ju cez --tag=safe-fetch-config:
use RoundlyConsulting\SafeFetch\Support\SystemHostResolver;
return [
// http too (local development, internal tools). https only by default.
'allow_http' => env('SAFE_FETCH_ALLOW_HTTP', false),
// null => any port 1–65535; otherwise the only ports a URL may use, e.g. [443].
'ports' => null,
'hosts' => [
// Non-empty => ONLY these hosts (exact or *.example.com). Still resolved,
// judged and pinned: an allowed host never makes a private address OK.
'allowed' => [],
// Refused by name, before any lookup.
'blocked' => [],
// Names whose addresses may be private (e.g. minio.internal). Still
// resolved and pinned.
'private' => [],
],
'ranges' => [
// Addresses / CIDRs exempt from the blocked-network table, e.g.
// ['127.0.0.1/32', '10.20.0.0/16']. 0.0.0.0/0 and ::/0 are refused.
'allowed' => [],
// Extra addresses / CIDRs always refused; they beat every allow.
'blocked' => [],
],
// The app's own host names (app.url's host + extra) are refused by name, and
// app.url's address when it is written as one: a request to yourself through
// a public load balancer is SSRF too.
'app_hosts' => [
'block' => true,
'extra' => [],
],
'redirects' => [
// Off by default: a redirect is returned to the caller unfollowed.
'enabled' => env('SAFE_FETCH_REDIRECTS', false),
// Hops followed at most, 0–10.
'max' => env('SAFE_FETCH_MAX_REDIRECTS', 3),
// null => 307 and 308 (method and body kept); SafeFetch::fetch() and
// SafeFetch::download(), which only send GETs, follow 301, 302, 303, 307
// and 308 then. Otherwise a subset of those five.
'statuses' => null,
// https -> http.
'allow_downgrade' => false,
// Header names also sent to another origin a redirect leads to
// (Accept, Content-Type, User-Agent and the like always are).
'forward_headers' => [],
],
// Http::safe(), SafeFetch::http()/guard() and the guarded Guzzle stack
// (SafeFetch::handlerStack()/guzzleClient()). Off (null) by default.
'request' => [
// Cut every response body at this many bytes (at least 1): the response
// keeps its status and headers and gains Safe-Fetch-Truncated: 1. A
// request's own `sink` is then refused. null => no cap.
'max_bytes' => env('SAFE_FETCH_REQUEST_MAX_BYTES'),
// The most seconds a request may take, every hop included, 1–600. A
// shorter ->timeout() wins; a request without one gets this. null =>
// only the request's own (Laravel's 30 s; none on a Guzzle client).
'timeout' => env('SAFE_FETCH_REQUEST_TIMEOUT'),
// Streamed responses (stream => true) only: fail a stream that sends
// nothing for this many seconds, 1–600. A shorter read_timeout on the
// request wins. null => only the request's own read_timeout.
'read_timeout' => env('SAFE_FETCH_REQUEST_READ_TIMEOUT'),
],
'fetch' => [
// SafeFetch::fetch() and download() body cap in bytes, at least 1.
'max_bytes' => env('SAFE_FETCH_MAX_BYTES', 5_242_880),
// SafeFetch::fetch() and download() time budget in seconds, 1–600, every
// hop included.
'timeout' => env('SAFE_FETCH_TIMEOUT', 30),
],
// The resolver behind every lookup: any class implementing
// RoundlyConsulting\SafeFetch\Contracts\HostResolver.
'resolver' => SystemHostResolver::class,
];Všetky kľúče
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
allow_http | SAFE_FETCH_ALLOW_HTTP | false | Okrem https aj http. |
ports | — | null | null pre ľubovoľný port, alebo neprázdny zoznam 1–65535 — jediné porty, ktoré URL adresa smie použiť. |
hosts.allowed | — | [] | Vzory hostiteľov; neprázdny zoznam znamená len tieto hostiteľov. Aj tak sa preložia, posúdia a pripnú. |
hosts.blocked | — | [] | Vzory hostiteľov odmietnuté podľa mena, ešte pred prekladom. |
hosts.private | — | [] | Vzory hostiteľov, ktorých adresy smú byť privátne (minio.internal) — nikdy nie cloudová metadátová adresa. |
ranges.allowed | — | [] | Adresy alebo CIDR vyňaté z tabuľky blokovaných sietí; nikdy 0.0.0.0/0, ::/0 ani IPv6 prefix, ktorý nesie celé IPv4. |
ranges.blocked | — | [] | Adresy alebo CIDR vždy odmietnuté; majú prednosť pred každým povolením. |
app_hosts.block | — | true | Odmietne vlastné mená hostiteľov aplikácie a adresu z app.url, ak je zapísaná ako adresa. |
app_hosts.extra | — | [] | Vzory hostiteľov, ktoré tiež znamenajú aplikáciu — hostiteľ z app.url vždy. |
redirects.enabled | SAFE_FETCH_REDIRECTS | false | Sledovať presmerovania; vypnuté vráti presmerovanie volajúcemu bez sledovania. |
redirects.max | SAFE_FETCH_MAX_REDIRECTS | 3 | Najviac sledovaných krokov, 0–10. |
redirects.statuses | — | null | null: 307 a 308 (pre fetch() a download() všetkých päť); inak podmnožina 301, 302, 303, 307, 308. |
redirects.allow_downgrade | — | false | Povoliť https → http. |
redirects.forward_headers | — | [] | Názvy hlavičiek, ktoré sa pošlú aj na iný origin, kam vedie presmerovanie. |
request.max_bytes | SAFE_FETCH_REQUEST_MAX_BYTES | null | null (bez limitu) alebo aspoň 1 — maxResponseBytes v pravidlách: Http::safe(), guard(), http() a chránený zásobník Guzzle orežú každé telo na túto dĺžku a označia ho Safe-Fetch-Truncated: 1; vlastný sink požiadavky sa potom odmietne. |
request.timeout | SAFE_FETCH_REQUEST_TIMEOUT | null | null (vlastný časový limit požiadavky) alebo 1–600 sekúnd — timeout v pravidlách: najdlhší čas chránenej požiadavky vrátane všetkých krokov. Kratší limit požiadavky má prednosť; požiadavka bez limitu (timeout(0), predvolený klient Guzzle) dostane tento. |
request.read_timeout | SAFE_FETCH_REQUEST_READ_TIMEOUT | null | null (vlastný read_timeout požiadavky) alebo 1–600 sekúnd — readTimeout v pravidlách: streamovaná odpoveď, ktorá toľko času nič nepošle, zlyhá s FetchFailed (timeout). Kratší read_timeout požiadavky má prednosť. |
fetch.max_bytes | SAFE_FETCH_MAX_BYTES | 5242880 | Aspoň 1 — limit tela pre fetch() a download(). |
fetch.timeout | SAFE_FETCH_TIMEOUT | 30 | 1–600 sekúnd — časový rozpočet fetch() a download(), vrátane všetkých krokov. |
resolver | — | SystemHostResolver::class | Ľubovoľná inštancovateľná trieda implementujúca Contracts\HostResolver; čokoľvek iné vyhodí výnimku pri vytvorení. |
Oba kľúče request.* sú predvolene vypnuté, takže chránená požiadavka sa správa ako doteraz, kým ich nenastavíte. fetch() a download() ich ignorujú — majú vlastné limity fetch.*. Pre jedno volanie ktorýkoľvek z nich zrušíte cez SafeFetch::policy()->maxResponseBytes(null) alebo ->timeout(null).
Prísne čítanie
- Každý kľúč sa číta prísne: nesprávny typ alebo hodnota mimo rozsahu vyhodí InvalidConfigurationException s názvom kľúča, namiesto tichého návratu k voľnejšiemu nastaveniu.
- Prázdna hodnota (KEY= v prostredí) znamená nenastavené a použije sa predvolená hodnota.
- Logické hodnoty v env prijímajú true/false, 1/0, on/off a yes/no. Zoznamy prijímajú pole alebo zoznam oddelený čiarkami v env.
- Nastavenia, ktoré by ochranu úplne vypli, sa odmietnu — 0.0.0.0/0 a ::/0 v ranges.allowed alebo IPv6 prefix, ktorý nesie celé IPv4 (::ffff:0:0/96, 2002::/16).
- Globálny vypínač neexistuje. Kód, ktorý ho potrebuje, si ponechá vlastné nastavenie a ochranu jednoducho nezavolá.
Premenné prostredia
SAFE_FETCH_ALLOW_HTTP=false
SAFE_FETCH_REDIRECTS=false
SAFE_FETCH_MAX_REDIRECTS=3
SAFE_FETCH_REQUEST_MAX_BYTES= # blank = no cap on guarded requests
SAFE_FETCH_REQUEST_TIMEOUT= # blank = the request's own timeout
SAFE_FETCH_REQUEST_READ_TIMEOUT= # blank = no idle limit on streamed responses
SAFE_FETCH_MAX_BYTES=5242880
SAFE_FETCH_TIMEOUT=30Vlastní hostitelia aplikácie
Hostiteľ z app.url sa vždy počíta ako aplikácia — bez schémy sa číta ako https (myapp.example, myapp.example:8080). Ak je app.url zapísaná ako adresa (https://52.10.20.30), odmietne sa ako app_host tiež, v akomkoľvek zápise. Iné verejné meno pre tú istú IP adresu sa nerozpozná: uveďte ho v app_hosts.extra.
Preklady
resources/lang/{en,sk}/messages.php obsahuje jeden riadok pre každý dôvod (status preberá :status) a validation.php správu pre safe_url (s :attribute). Ak ich chcete preformulovať, publikujte ich cez --tag=safe-fetch-translations.
Prejavte lásku k open source
Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.
Ďalšie spôsoby podpory vrátane kryptomienOdoslaním daru súhlasíte s našimi podmienkami prijímania darov.
Chcete to zabudovať do svojho produktu?
Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.