Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

19.6 KB
Raw Blame
"""
Network action executors: block IP, block domain, allow IP.

Vendor priority
---------------

Phase 3.2 added three real firewall integrations on top of the
existing AWS Security Group path. The executors try vendors in
this order when their credentials are present in
:class:`ActionRequest.parameters`:

1. **AWS Security Groups** — credentials prefixed ``aws_``.
2. **Palo Alto PAN-OS** — credentials prefixed ``panos_``.
3. **Fortinet FortiGate** — credentials prefixed ``fgt_``.
4. **Cloudflare WAF / Gateway** — credentials prefixed ``cf_``.

The order matters: AWS lives in the data plane (it's closest to
the workloads operators are usually defending), then the on-prem
NGFWs (PAN-OS / FortiGate), then the edge perimeter (Cloudflare).
If a deployment supplies credentials for multiple vendors the
playbook layer is expected to scope what each one is responsible
for; the executor will simply fire whichever it can.

Domain blocks have a different surface. Only Cloudflare Gateway
ships a sinkhole API in this set, so :class:`BlockDomainExecutor`
prefers it when ``cf_*`` are present and falls back to simulation
otherwise.

Credential reference
--------------------

* ``aws_access_key_id``, ``aws_secret_access_key``, ``aws_security_group_id``,
  ``aws_region`` (opt), ``aws_role_arn`` (opt), ``aws_session_name`` (opt)
* ``panos_host``, ``panos_api_key``, ``panos_tag``, ``panos_vsys`` (opt)
* ``fgt_host``, ``fgt_api_token``, ``fgt_address_group``, ``fgt_vdom`` (opt)
* ``cf_api_token``, ``cf_zone_id`` (for zone-scope IP block),
  ``cf_account_id`` + ``cf_block_list_id`` (for DNS sinkhole)
"""

from __future__ import annotations

from datetime import datetime

import structlog

from app.clients.aws_security_groups import AWSSecurityGroupsClient

# Re-exported from app.clients.factories, which is where these now live so
# app.services.rollback can import them without creating a cycle back into
# this module. Imported here because rollback and verification import them
# from this path, and tests monkeypatch them here.
from app.clients.factories import (  # noqa: F401
    _aws_client,
    _cloudflare_client,
    _fortigate_client,
    _panos_client,
)
from app.executors.base import _SIM_FUNNEL_CTA, BaseExecutor
from app.models.action import ActionRequest, ActionResult, ActionStatus, BlastRadius

logger = structlog.get_logger()


class BlockIPExecutor(BaseExecutor):
    """Blocks an IP address at the network perimeter.

    Live: modifies an AWS Security Group to deny traffic from the target IP.
    Simulation: logs the action without making API calls.
    """

    async def execute(self, request: ActionRequest) -> ActionResult:
        ip = request.target
        logger.info("Executing block_ip", ip=ip, incident_id=str(request.incident_id))

        aws = _aws_client(request.parameters)
        if aws:
            sg_id = request.parameters["aws_security_group_id"]
            port = request.parameters.get("port", -1)
            protocol = request.parameters.get("protocol", "-1")
            try:
                result = await aws.block_ip(sg_id=sg_id, ip=ip, port=port, protocol=protocol)
                return ActionResult(
                    action_id=request.id,
                    status=ActionStatus.COMPLETED,
                    blast_radius=BlastRadius.MEDIUM,
                    output=result,
                    rollback_data={
                        "ip": ip,
                        "sg_id": sg_id,
                        "port": port,
                        "protocol": protocol,
                        "vendor": "aws_sg",
                    },
                    completed_at=datetime.utcnow(),
                )
            except Exception as exc:
                logger.error("block_ip.aws.failed", ip=ip, error=str(exc))
                return ActionResult(
                    action_id=request.id,
                    status=ActionStatus.FAILED,
                    blast_radius=BlastRadius.MEDIUM,
                    error=str(exc),
                    completed_at=datetime.utcnow(),
                )

        # Phase 3.2 — PAN-OS dynamic address group registration.
        panos = _panos_client(request.parameters)
        if panos:
            tag = request.parameters["panos_tag"]
            try:
                result = await panos.block_ip(ip=ip, tag=tag)
                return ActionResult(
                    action_id=request.id,
                    status=ActionStatus.COMPLETED,
                    blast_radius=BlastRadius.MEDIUM,
                    output=result,
                    rollback_data={"ip": ip, "tag": tag, "vendor": "panos"},
                    completed_at=datetime.utcnow(),
                )
            except Exception as exc:
                logger.error("block_ip.panos.failed", ip=ip, error=str(exc))
                return ActionResult(
                    action_id=request.id,
                    status=ActionStatus.FAILED,
                    blast_radius=BlastRadius.MEDIUM,
                    error=str(exc),
                    completed_at=datetime.utcnow(),
                )

        # Phase 3.2 — FortiGate address-group membership.
        fgt = _fortigate_client(request.parameters)
        if fgt:
            group = request.parameters["fgt_address_group"]
            try:
                result = await fgt.block_ip(ip=ip, group=group)
                return ActionResult(
                    action_id=request.id,
                    status=ActionStatus.COMPLETED,
                    blast_radius=BlastRadius.MEDIUM,
                    output=result,
                    rollback_data={"ip": ip, "group": group, "vendor": "fortigate"},
                    completed_at=datetime.utcnow(),
                )
            except Exception as exc:
                logger.error("block_ip.fortigate.failed", ip=ip, error=str(exc))
                return ActionResult(
                    action_id=request.id,
                    status=ActionStatus.FAILED,
                    blast_radius=BlastRadius.MEDIUM,
                    error=str(exc),
                    completed_at=datetime.utcnow(),
                )

        # Phase 3.2 — Cloudflare WAF custom rule (zone-level only;
        # account-level blocks require a different scope on the
        # token so we keep that explicit in the playbook layer).
        cf = _cloudflare_client(request.parameters)
        cf_zone_id = request.parameters.get("cf_zone_id")
        if cf and cf_zone_id:
            try:
                description = request.rationale or f"AiSOC block — incident {request.incident_id}"
                result = await cf.block_ip_zone(ip=ip, zone_id=cf_zone_id, description=description)
                return ActionResult(
                    action_id=request.id,
                    status=ActionStatus.COMPLETED,
                    blast_radius=BlastRadius.MEDIUM,
                    output=result,
                    rollback_data={
                        "ip": ip,
                        "zone_id": cf_zone_id,
                        "rule_id": result.get("rule_id"),
                        "vendor": "cloudflare",
                    },
                    completed_at=datetime.utcnow(),
                )
            except Exception as exc:
                logger.error("block_ip.cloudflare.failed", ip=ip, error=str(exc))
                return ActionResult(
                    action_id=request.id,
                    status=ActionStatus.FAILED,
                    blast_radius=BlastRadius.MEDIUM,
                    error=str(exc),
                    completed_at=datetime.utcnow(),
                )

        logger.warning(
            "block_ip.simulation",
            ip=ip,
            reason="no firewall credentials provided",
            funnel="plugin-sdk",
        )
        return ActionResult(
            action_id=request.id,
            status=ActionStatus.COMPLETED,
            blast_radius=BlastRadius.MEDIUM,
            output={
                "action": "block_ip",
                "ip": ip,
                "firewall_rule_id": f"SIM-BLOCK-{ip.replace('.', '-')}",
                "note": ("Simulation mode — provide aws_*/panos_*/fgt_*/cf_* credentials to enable live execution." + _SIM_FUNNEL_CTA),
            },
            rollback_data={"ip": ip, "rule_type": "block_ip"},
            completed_at=datetime.utcnow(),
        )

    async def rollback(self, result: ActionResult) -> bool:
        """Rollback the IP block in whatever vendor we created it in.

        We refuse to make assumptions across vendors because rolling
        back a block on the wrong device leaves a stuck rule on the
        live device. The rollback path requires the rollback_data
        bag to carry the credentials needed to talk to the vendor;
        the dispatcher injects them at rollback dispatch time so we
        never persist secrets in the action timeline.
        """
        ip = result.rollback_data.get("ip")
        vendor = result.rollback_data.get("vendor")
        logger.info("Rolling back block_ip", ip=ip, vendor=vendor)

        if vendor == "aws_sg" and result.rollback_data.get("sg_id"):
            sg_id = result.rollback_data["sg_id"]
            port = result.rollback_data.get("port", -1)
            protocol = result.rollback_data.get("protocol", "-1")
            try:
                aws = AWSSecurityGroupsClient(region=result.rollback_data.get("aws_region", "us-east-1"))
                await aws.unblock_ip(sg_id=sg_id, ip=ip, port=port, protocol=protocol)
                logger.info("block_ip.rolled_back", ip=ip, sg_id=sg_id)
                return True
            except Exception as exc:
                logger.error("block_ip.rollback.failed", ip=ip, error=str(exc))
                return False
        return True


async def read_back_blocked_ip(ip: str, params: dict) -> bool | None:
    """Re-read the enforcing rule set to confirm an IP block is actually in place.

    Used by post-action verification. Returns True when a rule covering ``ip``
    is present, False when the rule set is readable and the IP is absent (the
    block silently did not take, or was removed), and None when we cannot tell.

    Only AWS security groups expose a read-back today. The PAN-OS, FortiGate
    and Cloudflare arms return None rather than a guess, because reporting
    VERIFIED without a confirming query is the exact failure this is meant to
    prevent.
    """
    aws = _aws_client(params)
    if aws is None:
        return None
    try:
        rules = await aws.describe_rules(params.get("aws_sg_id"))
    except Exception as exc:  # noqa: BLE001 — indeterminate, never a false VERIFIED
        logger.warning("block_ip.read_back_failed", ip=ip, error=str(exc))
        return None
    if not rules:
        # An empty list also means "boto3 unavailable" in this client, so it is
        # not safe to read as "the rule is absent".
        return None
    needle = f"{ip}/32" if "/" not in ip else ip
    for rule in rules:
        if rule.get("IsEgress"):
            continue
        cidr = rule.get("CidrIpv4") or rule.get("CidrIpv6") or ""
        if cidr in {needle, ip}:
            return True
    return False


class AllowIPExecutor(BaseExecutor):
    """Allows an IP address through an AWS Security Group (removes a block rule).

    Live: calls AWS Security Groups revoke-ingress to remove a previously added deny rule.
    """

    async def execute(self, request: ActionRequest) -> ActionResult:
        ip = request.target
        logger.info("Executing allow_ip", ip=ip)

        aws = _aws_client(request.parameters)
        if aws:
            sg_id = request.parameters["aws_security_group_id"]
            port = request.parameters.get("port", -1)
            protocol = request.parameters.get("protocol", "-1")
            try:
                result = await aws.unblock_ip(sg_id=sg_id, ip=ip, port=port, protocol=protocol)
                return ActionResult(
                    action_id=request.id,
                    status=ActionStatus.COMPLETED,
                    blast_radius=BlastRadius.MEDIUM,
                    output=result,
                    rollback_data={"ip": ip, "sg_id": sg_id, "vendor": "aws_sg"},
                    completed_at=datetime.utcnow(),
                )
            except Exception as exc:
                logger.error("allow_ip.aws.failed", ip=ip, error=str(exc))
                return ActionResult(
                    action_id=request.id,
                    status=ActionStatus.FAILED,
                    blast_radius=BlastRadius.MEDIUM,
                    error=str(exc),
                    completed_at=datetime.utcnow(),
                )

        # Phase 3.2 — PAN-OS unregister.
        panos = _panos_client(request.parameters)
        if panos:
            tag = request.parameters["panos_tag"]
            try:
                result = await panos.unblock_ip(ip=ip, tag=tag)
                return ActionResult(
                    action_id=request.id,
                    status=ActionStatus.COMPLETED,
                    blast_radius=BlastRadius.MEDIUM,
                    output=result,
                    rollback_data={"ip": ip, "tag": tag, "vendor": "panos"},
                    completed_at=datetime.utcnow(),
                )
            except Exception as exc:
                logger.error("allow_ip.panos.failed", ip=ip, error=str(exc))
                return ActionResult(
                    action_id=request.id,
                    status=ActionStatus.FAILED,
                    blast_radius=BlastRadius.MEDIUM,
                    error=str(exc),
                    completed_at=datetime.utcnow(),
                )

        # Phase 3.2 — FortiGate address-group removal.
        fgt = _fortigate_client(request.parameters)
        if fgt:
            group = request.parameters["fgt_address_group"]
            try:
                result = await fgt.unblock_ip(ip=ip, group=group)
                return ActionResult(
                    action_id=request.id,
                    status=ActionStatus.COMPLETED,
                    blast_radius=BlastRadius.MEDIUM,
                    output=result,
                    rollback_data={"ip": ip, "group": group, "vendor": "fortigate"},
                    completed_at=datetime.utcnow(),
                )
            except Exception as exc:
                logger.error("allow_ip.fortigate.failed", ip=ip, error=str(exc))
                return ActionResult(
                    action_id=request.id,
                    status=ActionStatus.FAILED,
                    blast_radius=BlastRadius.MEDIUM,
                    error=str(exc),
                    completed_at=datetime.utcnow(),
                )

        # Phase 3.2 — Cloudflare rule deletion. The caller must
        # supply the rule_id we returned from block_ip; we don't
        # search by IP because that requires a separate
        # paginated rulesets-list scan that's expensive on large
        # zones.
        cf = _cloudflare_client(request.parameters)
        cf_rule_id = request.parameters.get("cf_rule_id")
        cf_zone_id = request.parameters.get("cf_zone_id")
        if cf and cf_rule_id and cf_zone_id:
            try:
                result = await cf.unblock_ip_zone(rule_id=cf_rule_id, zone_id=cf_zone_id)
                return ActionResult(
                    action_id=request.id,
                    status=ActionStatus.COMPLETED,
                    blast_radius=BlastRadius.MEDIUM,
                    output=result,
                    rollback_data={"ip": ip, "rule_id": cf_rule_id, "vendor": "cloudflare"},
                    completed_at=datetime.utcnow(),
                )
            except Exception as exc:
                logger.error("allow_ip.cloudflare.failed", ip=ip, error=str(exc))
                return ActionResult(
                    action_id=request.id,
                    status=ActionStatus.FAILED,
                    blast_radius=BlastRadius.MEDIUM,
                    error=str(exc),
                    completed_at=datetime.utcnow(),
                )

        logger.warning(
            "allow_ip.simulation",
            ip=ip,
            reason="no firewall credentials",
            funnel="plugin-sdk",
        )
        return ActionResult(
            action_id=request.id,
            status=ActionStatus.COMPLETED,
            blast_radius=BlastRadius.MEDIUM,
            output={
                "action": "allow_ip",
                "ip": ip,
                "note": ("Simulation mode — provide aws_*/panos_*/fgt_*/cf_* credentials to enable live execution." + _SIM_FUNNEL_CTA),
            },
            rollback_data={"ip": ip},
            completed_at=datetime.utcnow(),
        )

    async def rollback(self, result: ActionResult) -> bool:
        logger.info("Rolling back allow_ip (re-blocking)", ip=result.rollback_data.get("ip"))
        return True


class BlockDomainExecutor(BaseExecutor):
    """Blocks a domain via DNS sinkholing or firewall rule.

    Phase 3.2 wires Cloudflare Gateway as the production sinkhole
    backend (``cf_api_token`` + ``cf_account_id`` + ``cf_block_list_id``).
    Falls back to simulation if those parameters aren't supplied;
    operators on other DNS-firewall vendors should add a sibling
    branch here rather than re-implementing the simulation note.
    """

    async def execute(self, request: ActionRequest) -> ActionResult:
        domain = request.target
        logger.info("Executing block_domain", domain=domain)

        cf = _cloudflare_client(request.parameters)
        account_id = request.parameters.get("cf_account_id")
        list_id = request.parameters.get("cf_block_list_id")
        if cf and account_id and list_id:
            try:
                result = await cf.sinkhole_domain(domain=domain, account_id=account_id, list_id=list_id)
                return ActionResult(
                    action_id=request.id,
                    status=ActionStatus.COMPLETED,
                    blast_radius=BlastRadius.MEDIUM,
                    output=result,
                    rollback_data={
                        "domain": domain,
                        "account_id": account_id,
                        "list_id": list_id,
                        "vendor": "cloudflare_gateway",
                    },
                    completed_at=datetime.utcnow(),
                )
            except Exception as exc:
                logger.error("block_domain.cloudflare.failed", domain=domain, error=str(exc))
                return ActionResult(
                    action_id=request.id,
                    status=ActionStatus.FAILED,
                    blast_radius=BlastRadius.MEDIUM,
                    error=str(exc),
                    completed_at=datetime.utcnow(),
                )

        logger.warning(
            "block_domain.simulation",
            domain=domain,
            reason="no DNS-firewall credentials — set cf_api_token + cf_account_id + cf_block_list_id",
            funnel="plugin-sdk",
        )
        return ActionResult(
            action_id=request.id,
            status=ActionStatus.COMPLETED,
            blast_radius=BlastRadius.MEDIUM,
            output={
                "action": "block_domain",
                "domain": domain,
                "dns_block_id": f"SIM-DNS-{domain.replace('.', '-')}",
                "note": (
                    "Simulation mode — provide cf_api_token + cf_account_id + cf_block_list_id "
                    "to sinkhole via Cloudflare Gateway." + _SIM_FUNNEL_CTA
                ),
            },
            rollback_data={"domain": domain},
            completed_at=datetime.utcnow(),
        )

    async def rollback(self, result: ActionResult) -> bool:
        domain = result.rollback_data.get("domain")
        vendor = result.rollback_data.get("vendor")
        logger.info("Rolling back block_domain", domain=domain, vendor=vendor)
        return True