lfnovo/open-notebook · critical · ValueError

The AWS IMDSv6 metadata address (fd00:ec2::254) is not allow

Error message

The AWS IMDSv6 metadata address (fd00:ec2::254) is not allowed for security reasons.

What it means

The URL contained the literal IPv6 address fd00:ec2::254 (AWS IMDSv6). Unlike link-local blocks this is a Unique Local Address, so it is matched by an explicit integer comparison against _AWS_IMDS_V6_ADDRESS. Direct literals (as opposed to DNS-resolved hostnames) get this constant message.

Source

Thrown at open_notebook/utils/url_validation.py:249

        raise ValueError(
            "Link-local addresses (169.254.x.x) are not allowed for security reasons. "
            "These addresses are used for cloud metadata endpoints."
        )

    # Block AWS's IMDSv6 metadata address - a Unique Local Address, not
    # link-local, so it needs its own explicit check. Compare without scope
    # ID so scoped forms (fd00:ec2::254%eth0) cannot bypass the sentinel.
    is_aws_imds_v6 = (
        isinstance(ip, ipaddress.IPv6Address)
        and int(ip) == int(_AWS_IMDS_V6_ADDRESS)
    )
    if is_aws_imds_v6:
        if resolved:
            raise ValueError(
                f"Hostname '{hostname}' resolves to the AWS IMDSv6 metadata address "
                "(fd00:ec2::254), which is not allowed for security reasons."
            )
        raise ValueError(
            "The AWS IMDSv6 metadata address (fd00:ec2::254) is not allowed for "
            "security reasons."
        )

View on GitHub (pinned to a7de90d38a)

Solutions

Use the actual AWS public API endpoints instead of the metadata address
If writing security tests, assert the ValueError is raised rather than expecting success

Defensive patterns

Strategy: validation

Validate before calling

import ipaddress
from urllib.parse import urlparse

AWS_IMDS_V6 = ipaddress.IPv6Address("fd00:ec2::254")

def is_imds_v6_literal(url: str) -> bool:
    host = urlparse(url).hostname or ""
    try:
        return ipaddress.ip_address(host) == AWS_IMDS_V6
    except ValueError:
        return False

Try / catch

try:
    validate_url(url)
except ValueError as e:
    if "IMDSv6" in str(e):
        return {"allowed": False, "reason": "aws-metadata-blocked"}
    raise

Prevention

Never configure [fd00:ec2::254] as an endpoint
Use AWS SDKs for metadata access, never user-configurable URLs

When it happens

Trigger: Passing 'http://[fd00:ec2::254]/' as a base_url to validate_url or prepare_pinned_http_target, or any discover/connection-test path built on it.

Common situations: SSRF attempts or security tests targeting the EC2 IPv6 metadata endpoint; hardening verification that the block works.

Related errors

AI-assisted analysis of lfnovo/open-notebook@a7de90d38a (2026-08-27). Data as JSON: /api/errors/979393bef75d87d9. Report an issue: GitHub.