Pravidlá cieľov

DestinationPolicy určuje, čo ochrana pustí nad rámec tabuľky blokovaných sietí. SafeFetch::policy() sú predvolené nakonfigurované pravidlá; každá with-metóda vráti nové pravidlá, takže volanie ich môže lokálne sprísniť alebo uvoľniť:

Http::safe(SafeFetch::policy()->allowHosts(['hooks.example.com'])->followRedirects())->post($url, $payload);

Metódy

Metódy, ktoré sprísňujú, sa voľne skladajú; čokoľvek, čo uvoľňuje, je volanie, ktoré to výslovne hovorí. Preto allowHosts() odmietne prázdny zoznam: zoznam, ktorý je náhodou prázdny ($tenant->hosts ?? []), by inak povolil každého hostiteľa. Rozvetvite kód podľa neho, alebo zavolajte withoutHostAllowlist(), ak naozaj chcete zoznam zrušiť.

Overenie hodnôt

Konštruktor overí všetko a vyhodí InvalidArgumentException: schémy len http a https, aspoň jedna; porty 1–65535, pri zozname aspoň jeden; položky hostiteľov sú kanonické mená alebo *. a meno — žiadna samotná *, schéma, port, cesta ani adresa (adresa patrí do rozsahov); rozsahy sú adresa alebo adresa/prefix; 0.0.0.0/0, ::/0 a každý IPv6 prefix, ktorý nesie celé IPv4 (::ffff:0:0/96, ::/96, 64:ff9b::/96, ::ffff:0:0:0/96, 2002::/16, alebo čokoľvek, čo ho obsahuje, napríklad 2000::/3), sa v povolených rozsahoch odmietnu; limit odpovede aspoň 1.

Vzory hostiteľov

Presné mená alebo *.example.com, porovnávané bez ohľadu na veľkosť písmen, s vynechaním jednej koncovej bodky na oboch stranách, medzinárodné mená ako punycode. *.example.com zodpovedá akejkoľvek subdoméne — nikdy samotnému example.com ani badexample.com.

Poradie pravidiel

Rozhoduje prvé zlyhanie:

• 1. Kanonizácia URL adresy (pozrite URL adresy a blokované siete).
• 2. Schéma, ktorú pravidlá nepovoľujú → scheme.
• 3. Port, ktorý pravidlá nepovoľujú → port.
• 4. Pravidlá mena: blokovaný hostiteľ → blocked (blocked_host, pred prekladom); jeden z hostiteľov aplikácie — alebo priamo zapísaná adresa, ktorá je jednou z jej adries — pri zapnutom blokovaní → blocked (app_host); striktný zoznam povolených, ktorý hostiteľa neobsahuje → not_allowed (priamo zapísaná adresa v ňom nikdy nie je); localhost alebo *.localhost, ktorý nie je privátnym hostiteľom → blocked (hostname).
• 5. Meno sa preloží raz (priamo zapísaná adresa je sama sebou); nič → unresolved.
• 6. Každá adresa: v blokovanom rozsahu → blocked (blocked_range); v tabuľke a ani v povolenom rozsahu, ani meno nie je privátny hostiteľ → blocked (private_address). Odpoveď, ktorá vôbec nie je adresa, sa odmietne bez ohľadu na to, čomu pravidlá dôverujú.

SafeFetch::precheck() spúšťa kroky 1–4 a krok 6 pre priamo zapísanú adresu, bez kroku 5.

Blok má prednosť pred povolením

• Povolený hostiteľ sa aj tak preloží, posúdi a pripne — „smie sa naň pýtať“, nikdy „smie byť privátny“.
• Privátny hostiteľ (minio.internal) sa aj tak preloží a pripne; z tabuľky sú vyňaté len jeho adresy (aj localhost uvedený medzi nimi sa prekladá).
• Privátny hostiteľ nikdy nevyníma cloudovú metadátovú adresu — celý link-local (169.254.0.0/16 a fe80::/10: metadáta inštancie, prihlasovacie údaje úloh ECS na 169.254.170.2, EKS Pod Identity na 169.254.170.23, Tencent na 169.254.0.23), fd00:ec2::/32, 100.100.100.200, 192.0.0.192, 168.63.129.16, ani IPv4 adresu, ktorú nesie IPv6 adresa. Späť ju môže povoliť len povolený rozsah.
• Rozsahy zodpovedajú adrese aj IPv4 adrese, ktorú nesie (127.0.0.1/32 pokrýva ::ffff:127.0.0.1), a IPv6 rozsah vnútri prefixu, ktorý nesie IPv4, pokrýva aj obyčajné IPv4 adresy, ktoré nesie (::ffff:8.8.8.0/120 pokrýva 8.8.8.8). Blokovaný rozsah, ktorý taký prefix obsahuje celý (2002::/16, ::/0), blokuje len jeho IPv6 tvary, nikdy všetky IPv4 adresy.

Pravidlá od nuly

Bežným začiatkom je SafeFetch::policy() s with-metódami — nesie vašu konfiguráciu. Oboje pravidlá sa však dajú zostaviť aj priamo; každý argument je pomenovaný a overený:

new DestinationPolicy(
    array $schemes = ['https'], ?array $ports = null,
    array $allowedHosts = [], array $blockedHosts = [], array $privateHosts = [],
    array $allowedRanges = [], array $blockedRanges = [],
    bool $blockAppHosts = true, array $appHosts = [],
    RedirectPolicy $redirects = new RedirectPolicy, ?int $maxResponseBytes = null,
    array $appAddresses = [],
)

new RedirectPolicy(
    bool $enabled = false, int $max = 3, ?array $statuses = null,
    bool $allowDowngrade = false, array $forwardHeaders = [],
)

use RoundlyConsulting\SafeFetch\DataTransferObjects\DestinationPolicy;
use RoundlyConsulting\SafeFetch\DataTransferObjects\RedirectPolicy;

$policy = new DestinationPolicy(
    ports: [443],
    allowedHosts: ['*.partner.example'],
    blockedRanges: ['203.0.113.0/24'],
    redirects: RedirectPolicy::methodPreserving(2),
    maxResponseBytes: 65_536,
);

$redirects = new RedirectPolicy(enabled: true, max: 5, statuses: [301, 302, 307, 308], forwardHeaders: ['X-Signature']);

Takto zostavené pravidlá o config/safe-fetch.php nič nevedia — ani o vlastných menách hostiteľov aplikácie: blockAppHosts je zapnuté, ale appHosts a appAddresses sú prázdne, kým ich neodovzdáte. Tabuľka blokovaných sietí platí bez ohľadu na pravidlá.