mesh.firewall.apply

Spustit na tomto hostiteli jako root příkazy, které vykresluje mesh.firewall: jedno povolení na pravidlo a zdrojovou síť na ufw nebo nftables, spustitelný soubor připuštěný v aplikačním firewallu macOS; nic jiného se nemění a každé zapsané pravidlo nese komentář `majordomus mesh`, aby šlo odlišit od pravidel operátora. Odmítne, aniž by cokoli spustilo, bez roota nebo bez backendu; zaznamená každý příkaz s jeho návratovým kódem a výstupem; a poté se firewallu zeptá znovu, takže verdikt je verdiktem firewallu. Nabízeno jen z příkazové řádky: spouští privilegovaný nástroj hostitele, což nesmí nic dosažitelné přes HTTP ani MCP.

command
experimentální
modul mesh
#mesh
#firewall

Zpřístupnění

Kde je tato jedna definice dosažitelná. Absence je explicitní: povrch, který není uveden, ji nenese.

povrch	jako
MCP	—
HTTP	—
příkazová řádka	majordomus mesh firewall apply

Schémata

Kanonický vstup a výstup z typů Rustu; schéma nástroje MCP a parametry a odpovědi OpenAPI se odvozují z nich.

vstup · FirewallInput

Vstup mesh.firewall a mesh.firewall.apply.

vlastnost	typ	povinné	popis
port	integer \| null	ne	Port, na kterém server tohoto checkoutu naslouchá mimo loopback, když tak činí: peer na něj volá protokolem linku, takže je třeba jej také povolit. Je-li vynechán, plán drží porty discovery a porty hubu, které deklarace tomuto stroji přidělí.

JSON Schema

{
  "additionalProperties": false,
  "description": "The input of `mesh.firewall` and `mesh.firewall.apply`.",
  "properties": {
    "port": {
      "description": "The port this checkout's server listens on beyond loopback, when it does: a peer\ndials it there on the link protocol, so it needs admitting too. Omitted, the plan\nholds the discovery ports and the hub ports the declaration gives this machine.",
      "format": "uint16",
      "maximum": 65535,
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    }
  },
  "title": "FirewallInput",
  "type": "object"
}

output · FirewallApplyReport

Co apply udělal: odmítnutí, když nic neběželo, každý příkaz, který běžel, s výsledkem, následné slovo firewallu a report, ze kterého příkazy pocházely. ok je verdikt firewallu po běhu, nikdy ne jen exit kódy příkazů.

use majordomus_cli::mesh::firewall::{apply, report, FirewallApplyReport};

let a: FirewallApplyReport = apply(report(None, &[], None));
assert!(!a.ok && a.applied.is_empty());
assert!(a.refused.as_deref().unwrap().contains("nothing to apply"));

vlastnost	typ	povinné	popis
aplikováno	array	ano	Příkazy v pořadí, s jejich exitem a výstupem.
před	reference	ano	Report, ze kterého příkazy pocházely.
pozorování	reference	ano	Slovo firewallu po provedení příkazů.
ok	boolean	ano	Zda se spustil každý příkaz a firewall poté plán připouští.
odmítnuto	string \| null	ne	Odmítnutí, když nic neběželo: ne root, nebo žádný backend.

JSON Schema

{
  "$defs": {
    "AdmitCommand": {
      "description": "One command that admits a rule: the rule's label, its argument vector exactly as\n`apply` executes it, and the same quoted as one line a person pastes into a root\nshell. The two are projections of one vector, so what the report shows is what runs.\n\n```\nuse std::net::Ipv4Addr;\nuse majordomus_cli::mesh::firewall::{plan, render, AdmitCommand, Backend};\nuse majordomus_cli::mesh::MeshConfig;\n\nlet config: MeshConfig = serde_json::from_value(serde_json::json!({\n    \"schema\": \"mesh/v1\", \"kind\": \"mesh-declaration\", \"id\": \"doc\", \"enabled\": true,\n})).unwrap();\nlet p = plan(Some(&config), &[Ipv4Addr::new(10, 0, 0, 2)], None);\nlet commands: Vec<AdmitCommand> = render(Backend::Ufw, &p, None);\nassert_eq!(commands[0].argv[0], \"ufw\");\nassert_eq!(commands[0].rule, \"udp/7741 to 239.255.77.77 from any\");\nassert_eq!(commands[0].line, \"ufw allow in proto udp to 239.255.77.77 port 7741 comment 'majordomus mesh: multicast discovery'\");\n```",
      "properties": {
        "argv": {
          "description": "The program and its arguments, as executed.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "line": {
          "description": "The same, quoted for a shell.",
          "type": "string"
        },
        "rule": {
          "description": "The rule it admits.",
          "type": "string"
        }
      },
      "required": [
        "rule",
        "argv",
        "line"
      ],
      "type": "object"
    },
    "Applied": {
      "description": "One command `apply` ran: the line, whether it exited 0 without printing an error,\nand everything it printed, so a refusal by the tool is read in the report and not in\na log.\n\n```\nuse majordomus_cli::mesh::firewall::Applied;\n\nlet a: Applied = serde_json::from_value(serde_json::json!({\n    \"line\": \"ufw allow in proto udp to 239.255.77.77 port 7741\", \"ok\": true, \"output\": \"Rule added\",\n})).unwrap();\nassert!(a.ok && a.output == \"Rule added\");\n```",
      "properties": {
        "line": {
          "description": "The line that ran.",
          "type": "string"
        },
        "ok": {
          "description": "Whether it exited 0.",
          "type": "boolean"
        },
        "output": {
          "description": "What it printed.",
          "type": "string"
        }
      },
      "required": [
        "line",
        "ok",
        "output"
      ],
      "type": "object"
    },
    "Backend": {
      "description": "The firewall front this host runs, as far as the executable can tell without privilege:\ndecided by `detect` from the platform and the path, and the thing `render`,\n`observe` and `apply` are specific to.\n\n```\nuse majordomus_cli::mesh::firewall::Backend;\n\nassert_eq!(serde_json::to_value(Backend::ApplicationFirewall).unwrap(), \"application_firewall\");\nassert_eq!(Backend::None.as_str(), \"none\");\n```",
      "oneOf": [
        {
          "const": "ufw",
          "description": "Uncomplicated Firewall, the Debian and Ubuntu front: `ufw` is on the path.",
          "type": "string"
        },
        {
          "const": "nftables",
          "description": "nftables without ufw in front: `nft` is on the path.",
          "type": "string"
        },
        {
          "const": "application_firewall",
          "description": "macOS: the application firewall (`socketfilterfw`), which admits executables, not ports.",
          "type": "string"
        },
        {
          "const": "none",
          "description": "No firewall front this executable knows; nothing is observed and nothing is applied.",
          "type": "string"
        }
      ]
    },
    "FirewallObservation": {
      "description": "The firewall's own word, judged against the plan: the state, the evidence behind it,\nand the labels of the rules not admitted when the state is `missing`.\n\n```\nuse majordomus_cli::mesh::firewall::{judge_ufw, plan, FirewallObservation, FirewallObservationState};\n\nlet o: FirewallObservation = judge_ufw(\"Status: inactive\\n\", &plan(None, &[], None));\nassert_eq!(o.state, FirewallObservationState::Inactive);\nassert!(o.missing.is_empty() && o.detail.contains(\"inactive\"));\n```",
      "properties": {
        "detail": {
          "description": "The evidence: the status line, the rules found, or the refusal.",
          "type": "string"
        },
        "missing": {
          "description": "The rules not admitted, by label, when `state` is `missing`.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "state": {
          "$ref": "#/$defs/FirewallObservationState",
          "description": "The verdict."
        }
      },
      "required": [
        "state",
        "detail"
      ],
      "type": "object"
    },
    "FirewallObservationState": {
      "description": "What the host's firewall says about the plan, as one word. Only `missing` is a failure\non its own; `unobservable` is an absence that the kernel log may still turn into one.\n\n```\nuse majordomus_cli::mesh::firewall::FirewallObservationState;\n\nassert_eq!(serde_json::to_value(FirewallObservationState::Unobservable).unwrap(), \"unobservable\");\n```",
      "oneOf": [
        {
          "const": "no_backend",
          "description": "No backend to ask.",
          "type": "string"
        },
        {
          "const": "inactive",
          "description": "The firewall is off: nothing filters, nothing is needed.",
          "type": "string"
        },
        {
          "const": "present",
          "description": "Every rule of the plan is admitted.",
          "type": "string"
        },
        {
          "const": "missing",
          "description": "At least one rule of the plan is not admitted.",
          "type": "string"
        },
        {
          "const": "unobservable",
          "description": "The firewall could not be asked from this process — it needs root.",
          "type": "string"
        }
      ]
    },
    "FirewallPlan": {
      "description": "What the declaration implies this host must admit: the rules, the networks they admit\nfrom, the hub ports this machine is listed for, and the addresses the plan saw. The\nanswer of `plan`; an empty `rules` is \"nothing is needed\", which is the answer for no\ndeclaration and for a disabled one.\n\n```\nuse majordomus_cli::mesh::firewall::{plan, FirewallPlan};\n\nlet nothing: FirewallPlan = plan(None, &[], None);\nassert!(nothing.rules.is_empty() && nothing.hub_ports.is_empty() && nothing.networks.is_empty());\n```",
      "properties": {
        "hub_ports": {
          "description": "The ports of the declared hubs this machine is.",
          "items": {
            "format": "uint16",
            "maximum": 65535,
            "minimum": 0,
            "type": "integer"
          },
          "type": "array"
        },
        "local_addresses": {
          "description": "This machine's addresses, as the plan saw them.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "networks": {
          "description": "The private networks peers come from: the enclosing ranges of every address the\ndeclaration names, or of this machine's own when it names none.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "rules": {
          "description": "The admissions, in a fixed order.",
          "items": {
            "$ref": "#/$defs/FirewallRule"
          },
          "type": "array"
        }
      },
      "required": [
        "local_addresses",
        "networks",
        "hub_ports",
        "rules"
      ],
      "type": "object"
    },
    "FirewallReport": {
      "description": "The whole report: the plan, the backend, the commands, the firewall's word and the\nkernel's, with one verdict sentence and one `ok`. What `mesh.firewall` answers and\nwhat the doctor's `firewall` check reads.\n\n```\nuse majordomus_cli::mesh::firewall::{report, FirewallReport, BLOCK_WINDOW_SECONDS};\n\nlet r: FirewallReport = report(None, &[], None);\nassert!(r.ok && r.commands.is_empty());\nassert_eq!(r.window_seconds, BLOCK_WINDOW_SECONDS);\nassert_eq!(r.platform, std::env::consts::OS);\n```",
      "properties": {
        "backend": {
          "$ref": "#/$defs/Backend",
          "description": "The firewall front found."
        },
        "blocked_recently": {
          "additionalProperties": {
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          },
          "description": "Drops the kernel logged toward the plan's ports within the window, per port;\nabsent when the log could not be read.",
          "type": [
            "object",
            "null"
          ]
        },
        "commands": {
          "description": "The commands that admit it on this backend; what `apply` runs.",
          "items": {
            "$ref": "#/$defs/AdmitCommand"
          },
          "type": "array"
        },
        "executable": {
          "description": "The executable the server runs as, which is what the macOS firewall admits.",
          "type": [
            "string",
            "null"
          ]
        },
        "observation": {
          "$ref": "#/$defs/FirewallObservation",
          "description": "The firewall's own word about the plan."
        },
        "ok": {
          "description": "Whether the host admits the mesh as far as it can be observed: nothing missing, and\nnothing logged as dropped.",
          "type": "boolean"
        },
        "plan": {
          "$ref": "#/$defs/FirewallPlan",
          "description": "What the declaration implies this host must admit."
        },
        "platform": {
          "description": "The platform (`linux`, `macos`, …).",
          "type": "string"
        },
        "verdict": {
          "description": "The sentence a person reads.",
          "type": "string"
        },
        "window_seconds": {
          "description": "The window `blocked_recently` covers, in seconds.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "ok",
        "platform",
        "backend",
        "plan",
        "commands",
        "observation",
        "window_seconds",
        "verdict"
      ],
      "type": "object"
    },
    "FirewallRule": {
      "description": "One inbound admission the mesh needs on this host: a protocol and a port, the group it is\naddressed to when it is multicast, the networks it may come from, and the sentence that\nsays why. A rule is derived, never written by hand; `FirewallRule::label` is how a\nverdict names it.\n\n```\nuse majordomus_cli::mesh::firewall::{FirewallRule, Protocol, Role};\n\nlet rule = FirewallRule {\n    role: Role::Hub,\n    protocol: Protocol::Tcp,\n    port: 8791,\n    destination: None,\n    sources: vec![\"192.168.7.0/24\".into()],\n    reason: \"this machine is a declared rendezvous hub\".into(),\n};\nassert_eq!(rule.label(), \"tcp/8791 from 192.168.7.0/24\");\n```",
      "properties": {
        "destination": {
          "description": "The destination address when it is a multicast group; `None` for this host's own.",
          "type": [
            "string",
            "null"
          ]
        },
        "port": {
          "description": "The destination port.",
          "format": "uint16",
          "maximum": 65535,
          "minimum": 0,
          "type": "integer"
        },
        "protocol": {
          "$ref": "#/$defs/Protocol",
          "description": "The transport protocol."
        },
        "reason": {
          "description": "The sentence a person reads beside the rule.",
          "type": "string"
        },
        "role": {
          "$ref": "#/$defs/Role",
          "description": "Why."
        },
        "sources": {
          "description": "The networks the traffic may come from, as CIDR; empty admits any source, which is\nonly ever the case for the multicast group, whose TTL keeps it on the segment.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "role",
        "protocol",
        "port",
        "sources",
        "reason"
      ],
      "type": "object"
    },
    "Protocol": {
      "description": "The transport protocol of a rule: discovery is datagrams, registration and the link\nprotocol are connections. Serialised as the word a firewall front takes.\n\n```\nuse majordomus_cli::mesh::firewall::Protocol;\n\nassert_eq!(serde_json::to_value(Protocol::Udp).unwrap(), \"udp\");\nassert_eq!(serde_json::to_value(Protocol::Tcp).unwrap(), \"tcp\");\n```",
      "oneOf": [
        {
          "const": "udp",
          "description": "Datagrams: discovery.",
          "type": "string"
        },
        {
          "const": "tcp",
          "description": "Connections: the hub's registrations and the link protocol.",
          "type": "string"
        }
      ]
    },
    "Role": {
      "description": "Why a rule exists: which part of the declaration implied it. The role is what a person\nreads beside the rule and what a verdict names, and it is serialised in snake case.\n\n```\nuse majordomus_cli::mesh::firewall::Role;\n\nassert_eq!(serde_json::to_value(Role::Hub).unwrap(), \"hub\");\nlet back: Role = serde_json::from_value(serde_json::json!(\"multicast\")).unwrap();\nassert_eq!(back, Role::Multicast);\n```",
      "oneOf": [
        {
          "const": "multicast",
          "description": "The declared multicast group: every runtime of the segment advertises to it.",
          "type": "string"
        },
        {
          "const": "broadcast",
          "description": "The declared broadcast port, when broadcast is a permitted fallback.",
          "type": "string"
        },
        {
          "const": "hub",
          "description": "This machine is a declared rendezvous hub: the fleet registers here.",
          "type": "string"
        },
        {
          "const": "link",
          "description": "This machine's server is dialed by peers on the link protocol.",
          "type": "string"
        }
      ]
    }
  },
  "description": "What `apply` did: the refusal when nothing ran, every command that ran with its\noutcome, the firewall's word afterwards, and the report the commands came from. `ok`\nis the firewall's verdict after the run, never the commands' exit codes alone.\n\n```\nuse majordomus_cli::mesh::firewall::{apply, report, FirewallApplyReport};\n\nlet a: FirewallApplyReport = apply(report(None, &[], None));\nassert!(!a.ok && a.applied.is_empty());\nassert!(a.refused.as_deref().unwrap().contains(\"nothing to apply\"));\n```",
  "properties": {
    "applied": {
      "description": "The commands, in order, with their exit and output.",
      "items": {
        "$ref": "#/$defs/Applied"
      },
      "type": "array"
    },
    "before": {
      "$ref": "#/$defs/FirewallReport",
      "description": "The report the commands came from."
    },
    "observation": {
      "$ref": "#/$defs/FirewallObservation",
      "description": "The firewall's word after the commands ran."
    },
    "ok": {
      "description": "Whether every command ran and the firewall admits the plan afterwards.",
      "type": "boolean"
    },
    "refused": {
      "description": "The refusal, when nothing ran: not root, or no backend.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "ok",
    "applied",
    "observation",
    "before"
  ],
  "title": "FirewallApplyReport",
  "type": "object"
}

Politiky

benchmark: waived — prominuto: destructive
cache: vypnuto — každé volání spustí handler

Cíle benchmarku

Odvozeno z registru pro tento repozitář: jeden požadavek na transport a případy, které poskytuje typ vstupu. Celá matice je na stránce měření výkonu.

transport	state	případy	targets
direct	prominuto (destruktivní)	0