Install the command-line tool from Homebrew, the install scripts or crates.io

* Offer a restart once setup finishes

* Describe the restart without naming one variable

README.md

@@ -0,0 +1,83 @@
+# Strix Firewall
+
+Stops malicious packages before they install. When a package manager downloads a package, the firewall checks its name and version against Strix's denylist and [OSV](https://osv.dev) malware advisories, and fails the download if either flags it.
+
+It covers npm, pnpm, bun, pip, uv, pipenv, pdm, cargo, gem and go.
+
+## Install
+
+**Command-line tool**, with any of:
+
+```sh
+brew install usestrix/tap/strix-firewall
+curl -LsSf https://github.com/usestrix/firewall/releases/latest/download/strix-firewall-installer.sh | sh
+cargo install strix-firewall
+```
+
+On Windows:
+
+```powershell
+powershell -c "irm https://github.com/usestrix/firewall/releases/latest/download/strix-firewall-installer.ps1 | iex"
+```
+
+From a clone, `cargo install --path core`.
+
+**Whole-machine firewall** (macOS 13 or later on Apple Silicon):
+
+1. Build `Firewall.pkg` (see [Building the macOS app](#building-the-macos-app)) and open it.
+2. Open **StrixFirewall** from Applications and click **Install**.
+3. Approve the system extension, the network configuration and the certificate when macOS asks, then restart.
+
+It then lives in the menu bar. To remove it, choose **Setup** from the menu and click **Uninstall**.
+
+## Use
+
+Put `firewall` in front of a package manager command:
+
+```sh
+firewall npm install left-pad
+```
+
+Or alias the manager so every install is checked:
+
+```sh
+alias npm='firewall npm'
+```
+
+The whole-machine firewall needs no setup: it checks downloads from every process.
+
+## Configure
+
+Settings come from an optional `config.json`; a file only needs the keys it changes:
+
+```json
+{
+  "min_age_hours": 24,
+  "allow": { "npm": [{ "name": "left-pad", "version": "1.3.0" }] }
+}
+```
+
+| Key | Default | |
+| --- | --- | --- |
+| `fail_open` | `true` | Allow a package when it could not be checked |
+| `min_age_hours` | `0` | Hold back versions newer than this; 0 turns it off |
+| `allow` | `{}` | Packages never screened, by ecosystem (`npm`, `pypi`, `cargo`, `gem`, `go`); every version when `version` is absent |
+| `telemetry` | `true` | Send screening events, errors and a heartbeat to Strix |
+| `port` | `8080` | Port for `firewall serve` |
+
+The command-line tool reads `~/Library/Application Support/com.usestrix.firewall/config.json` on macOS and `~/.config/firewall/config.json` on Linux. On macOS, `/Library/Application Support/Firewall/config.json` overrides it key by key (allow lists add up), and is the only file the whole-machine firewall reads.
+
+## Building the macOS app
+
+It needs [XcodeGen](https://github.com/yonaskolb/XcodeGen), a Developer ID certificate, and Developer ID profiles for `com.usestrix.firewall` and `com.usestrix.firewall.extension`:
+
+```sh
+echo TEAM=<Apple team ID> > macos/.env
+echo NOTARY_PROFILE=<notarytool keychain profile> >> macos/.env
+macos/build.sh         # builds and notarizes macos/build/Firewall.pkg
+macos/build.sh debug   # signs with Apple Development and skips notarization
+```
+
+## License
+
+Apache 2.0. See [LICENSE](LICENSE).

core/src/aliasing/forward.rs

@@ -82,7 +82,7 @@ async fn handle(req: Request, firewall: &Firewall) -> Result<Response, Infallibl
     };
 
     let reason = policies::screen(&url, firewall).await;
-    telemetry::screened(firewall, &url, reason.is_some());
+    telemetry::screened(firewall, &url, reason.as_deref());
     if let Some(reason) = reason {
         warn!(method = %req.method(), %url, %reason, "blocked");
         return Ok(blocked(&reason));

core/src/config/mod.rs

@@ -1,6 +1,7 @@
 use crate::policies::registries::{Registry, BUILT_IN};
 use directories::ProjectDirs;
 use serde::Deserialize;
+use serde_json::{Map, Value};
 use std::collections::HashMap;
 use std::io::{Error, ErrorKind};
 use std::path::PathBuf;
@@ -68,18 +69,31 @@ impl Default for DenylistSource {
 }
 
 impl FirewallConfig {
-    /// A missing file means defaults; a bad one is an error, so the policy is never quietly relaxed.
     pub fn load() -> std::io::Result<Self> {
-        let Some(path) = path() else {
-            return Ok(Self::default());
-        };
-        let text = match std::fs::read_to_string(&path) {
-            Ok(text) => text,
-            Err(e) if e.kind() == ErrorKind::NotFound => return Ok(Self::default()),
-            Err(e) => return Err(Error::new(e.kind(), format!("{}: {e}", path.display()))),
-        };
-        serde_json::from_str(&text)
-            .map_err(|e| Error::new(ErrorKind::InvalidData, format!("{}: {e}", path.display())))
+        let mut paths: Vec<PathBuf> = path().into_iter().collect();
+        paths.extend(crate::os::system_config());
+        Self::load_from(&paths)
+    }
+
+    /// Later files win key by key, but allow lists add up.
+    /// A bad file is an error, so the policy is never quietly relaxed.
+    pub fn load_from(paths: &[PathBuf]) -> std::io::Result<Self> {
+        let mut merged = Map::new();
+        for path in paths {
+            let text = match std::fs::read_to_string(path) {
+                Ok(text) => text,
+                Err(e) if e.kind() == ErrorKind::NotFound => continue,
+                Err(e) => return Err(Error::new(e.kind(), format!("{}: {e}", path.display()))),
+            };
+            let invalid = |e| Error::new(ErrorKind::InvalidData, format!("{}: {e}", path.display()));
+            let layer: Value = serde_json::from_str(&text).map_err(invalid)?;
+            FirewallConfig::deserialize(&layer).map_err(invalid)?;
+            let Value::Object(layer) = layer else {
+                unreachable!("a config parses only from an object");
+            };
+            merge(&mut merged, layer);
+        }
+        Ok(serde_json::from_value(Value::Object(merged)).expect("each layer parsed on its own"))
     }
 
     pub fn local_url(&self, path: &str) -> String {
@@ -103,3 +117,15 @@ pub fn path() -> Option<PathBuf> {
     let dirs = ProjectDirs::from("com", "usestrix", "firewall")?;
     Some(dirs.config_dir().join("config.json"))
 }
+
+fn merge(base: &mut Map<String, Value>, top: Map<String, Value>) {
+    for (key, value) in top {
+        match (base.get_mut(&key), value) {
+            (Some(Value::Object(base)), Value::Object(top)) => merge(base, top),
+            (Some(Value::Array(base)), Value::Array(top)) => base.extend(top),
+            (_, value) => {
+                base.insert(key, value);
+            }
+        }
+    }
+}

core/src/main.rs

@@ -56,6 +56,7 @@ fn options() -> Command {
 }
 
 fn serve() -> ! {
+    telemetry::set_mode("proxy");
     let config = load();
     let port = config.port;
     print_setup(&config);
@@ -83,6 +84,7 @@ fn uninstall() -> ! {
 }
 
 fn run(invocation: Invocation) -> ! {
+    telemetry::set_mode("wrapper");
     let command = &invocation.program;
     let port = match aliasing::spawn(0, load()) {
         Ok(port) => port,

core/src/mitm/screen.rs

@@ -37,7 +37,7 @@ where
     async fn serve(&self, req: Request) -> Result<Response, Self::Error> {
         if let Some(url) = https_url(&req) {
             let reason = policies::screen(&url, &self.firewall).await;
-            telemetry::screened(&self.firewall, &url, reason.is_some());
+            telemetry::screened(&self.firewall, &url, reason.as_deref());
             if let Some(reason) = reason {
                 warn!(%url, "blocked by firewall: {reason}");
                 return Ok(blocked(&reason));

core/src/os/macos/mod.rs

@@ -23,6 +23,7 @@ use rama::rt::Executor;
 use rama::telemetry::tracing::apple::oslog::{OsLogLayer, Privacy};
 use rama::{Layer, Service};
 use std::convert::Infallible;
+use std::path::PathBuf;
 use std::sync::Arc;
 use tracing_subscriber::layer::SubscriberExt;
 use tracing_subscriber::util::SubscriberInitExt;
@@ -32,6 +33,7 @@ const KEYCHAIN_SERVICE: &str = BUNDLE_ID;
 const KEYCHAIN_ACCOUNT: &str = "ca";
 /// Must match `macos/LaunchAgents/com.usestrix.firewall.env.plist`, which points npm at it.
 const CA_FILE: &str = "/Library/Application Support/Firewall/ca.pem";
+const CONFIG_FILE: &str = "/Library/Application Support/Firewall/config.json";
 
 #[derive(Clone)]
 struct Handler {
@@ -97,9 +99,14 @@ impl TransparentProxyHandlerFactory for Factory {
     }
 }
 
+pub fn system_config() -> Option<PathBuf> {
+    Some(CONFIG_FILE.into())
+}
+
 fn handler(exec: Executor) -> Result<Handler, BoxError> {
+    telemetry::set_mode("extension");
     telemetry::heartbeat();
-    let config = FirewallConfig::load().inspect_err(|_| telemetry::error("config"))?;
+    let config = FirewallConfig::load_from(&[CONFIG_FILE.into()]).inspect_err(|_| telemetry::error("config"))?;
     let firewall = Arc::new(Firewall::new(config));
     let hosts = firewall.hosts();
     let key = enclave::EnclaveKey::load_or_create().inspect_err(|_| telemetry::error("enclave"))?;

core/src/os/mod.rs

@@ -2,10 +2,15 @@
 pub mod macos;
 
 #[cfg(target_os = "macos")]
-pub use macos::uninstall;
+pub use macos::{system_config, uninstall};
 
 /// Elsewhere nothing is installed system-wide.
 #[cfg(not(target_os = "macos"))]
 pub fn uninstall() -> Result<(), rama::error::BoxError> {
     Ok(())
 }
+
+#[cfg(not(target_os = "macos"))]
+pub fn system_config() -> Option<std::path::PathBuf> {
+    None
+}

core/src/policies/mod.rs

@@ -72,6 +72,9 @@ pub async fn screen(url: &str, firewall: &Firewall) -> Option<String> {
         Some((_, Verdict::Deny(reason))) => {
             Some(format!("{} {reason}", pkg.label()))
         }
+        Some((filter, Verdict::Unknown(e))) if !firewall.config.fail_open => {
+            Some(format!("{} could not be checked by {filter} ({e})", pkg.label()))
+        }
         _ => None,
     }
 }

core/src/proxy/mod.rs

@@ -1,6 +1,6 @@
 use crate::http::{blocked, reply, text};
 use crate::policies::{self, Check, Decision};
-use crate::{Firewall, FirewallConfig};
+use crate::{telemetry, Firewall, FirewallConfig};
 use rama::http::body::util::BodyExt;
 use rama::http::client::EasyHttpWebClient;
 use rama::http::header::CONTENT_TYPE;
@@ -19,6 +19,7 @@ pub fn serve(config: FirewallConfig) -> std::io::Result<()> {
     bound.set_nonblocking(true)?;
     crate::runtime()?.block_on(async move {
         let firewall = Arc::new(Firewall::new(config));
+        telemetry::heartbeat();
         let exec = Executor::default();
         let listener = TcpListener::try_from_std_tcp_listener(bound, exec.clone())?;
         let server = HttpServer::auto(exec).service(service_fn(move |req: Request| {
@@ -44,6 +45,7 @@ async fn screen(target: String, firewall: &Firewall) -> Response {
         }
         Decision::Block { eco, pkg, filter, reason } => {
             let reason = format!("{} {reason}", pkg.label());
+            telemetry::screened_package(eco, &pkg, Some(&reason));
             warn!(%eco, %filter, "blocked by firewall: {reason}");
             blocked(&reason)
         }
@@ -51,9 +53,11 @@ async fn screen(target: String, firewall: &Firewall) -> Response {
             match &check {
                 Check::NoPackage => {}
                 Check::Allowed(pkg) => {
+                    telemetry::screened_package(target.eco, pkg, None);
                     info!(eco = %target.eco, pkg = %pkg.label(), "cleared by every filter")
                 }
                 Check::Unverified { pkg, filter, error } => {
+                    telemetry::screened_package(target.eco, pkg, None);
                     info!(pkg = %pkg.label(), %filter, %error, "filter could not check, allowing")
                 }
             }

core/src/telemetry.rs

@@ -1,10 +1,11 @@
+use crate::policies::Package;
 use crate::{Firewall, FirewallConfig};
 use rama::http::client::EasyHttpWebClient;
 use rama::http::header::CONTENT_TYPE;
 use rama::http::service::client::HttpClientExt;
 use rama::rt::blocking::Runtime;
 use serde_json::{json, Value};
-use std::sync::{LazyLock, Mutex};
+use std::sync::{LazyLock, Mutex, OnceLock};
 use std::time::Duration;
 use time::format_description::well_known::Rfc3339;
 use time::OffsetDateTime;
@@ -29,29 +30,40 @@ static TELEMETRY: LazyLock<Option<Telemetry>> = LazyLock::new(|| {
     })
 });
 
+/// How the firewall is running: "extension", "wrapper" or "proxy".
+static MODE: OnceLock<&'static str> = OnceLock::new();
+
 struct Telemetry {
     key: &'static str,
     session: String,
     events: Mutex<Vec<Value>>,
 }
 
-pub fn screened(firewall: &Firewall, url: &str, blocked: bool) {
+pub fn screened(firewall: &Firewall, url: &str, reason: Option<&str>) {
     if TELEMETRY.is_none() {
         return;
     }
     let Some((registry, rest)) = firewall.match_on(url, |r| r.upstream) else {
         return;
     };
-    let Some(pkg) = firewall.resolve(registry, rest).pkg else {
-        return;
-    };
-    let mut properties = json!({ "eco": registry.eco, "blocked": blocked });
-    if blocked {
+    if let Some(pkg) = firewall.resolve(registry, rest).pkg {
+        screened_package(registry.eco, &pkg, reason);
+    }
+}
+
+pub fn screened_package(eco: &str, pkg: &Package, reason: Option<&str>) {
+    let mut properties = json!({ "eco": eco, "blocked": reason.is_some() });
+    if let Some(reason) = reason {
         properties["package"] = pkg.label().into();
+        properties["reason"] = reason.into();
     }
     record("package_screened", properties);
 }
 
+pub fn set_mode(mode: &'static str) {
+    MODE.set(mode).ok();
+}
+
 pub fn error(kind: &'static str) {
     record("error", json!({ "kind": kind }));
 }
@@ -81,6 +93,7 @@ pub fn flush() {
 fn record(event: &str, mut properties: Value) {
     let Some(telemetry) = &*TELEMETRY else { return };
     properties["distinct_id"] = telemetry.session.clone().into();
+    properties["mode"] = MODE.get().copied().into();
     properties["os"] = std::env::consts::OS.into();
     properties["arch"] = std::env::consts::ARCH.into();
     properties["$process_person_profile"] = false.into();

core/tests/config.rs

@@ -1,6 +1,6 @@
 use firewall::config::path;
 use firewall::policies::filters::consult;
-use firewall::policies::Package;
+use firewall::policies::{screen, Package};
 use firewall::{Firewall, FirewallConfig};
 
 #[test]
@@ -21,6 +21,23 @@ fn the_config_lives_under_the_config_directory() {
     assert!(path.ends_with("config.json"), "{}", path.display());
 }
 
+#[test]
+fn a_later_file_wins_and_allow_lists_add_up() {
+    let dir = std::env::temp_dir().join(format!("firewall-layers-{}", std::process::id()));
+    std::fs::create_dir_all(&dir).expect("temp dir");
+    let user = dir.join("user.json");
+    let system = dir.join("system.json");
+    std::fs::write(&user, r#"{"min_age_hours": 1, "fail_open": false, "allow": {"npm": [{"name": "a"}]}}"#).expect("write");
+    std::fs::write(&system, r#"{"min_age_hours": 24, "allow": {"npm": [{"name": "b"}]}}"#).expect("write");
+    let missing = dir.join("missing.json");
+    let config = FirewallConfig::load_from(&[user, system, missing]).expect("loads");
+    std::fs::remove_dir_all(&dir).ok();
+    assert_eq!(config.min_age_hours, 24);
+    assert!(!config.fail_open);
+    let names: Vec<&str> = config.allow["npm"].iter().map(|p| p.name.as_str()).collect();
+    assert_eq!(names, ["a", "b"]);
+}
+
 #[tokio::test]
 async fn an_allowed_version_skips_the_filters() {
     // An unreachable denylist would otherwise leave the package unchecked.
@@ -31,3 +48,12 @@ async fn an_allowed_version_skips_the_filters() {
     assert!(consult(&firewall, registry, &pkg("0.20.0")).await.is_none());
     assert!(consult(&firewall, registry, &pkg("0.21.0")).await.is_some());
 }
+
+#[tokio::test]
+async fn failing_closed_blocks_what_could_not_be_checked() {
+    let config = r#"{"fail_open": false, "denylist": {"base": "http://127.0.0.1:1"}}"#;
+    let firewall = Firewall::new(serde_json::from_str(config).expect("parses"));
+    let url = "https://registry.npmjs.org/left-pad/-/left-pad-1.3.0.tgz";
+    let blocked = screen(url, &firewall).await.unwrap_or_default();
+    assert!(blocked.contains("could not be checked"), "{blocked:?}");
+}

macos/App/AppIcon.icon/icon.json

@@ -0,0 +1,24 @@
+{
+  "fill" : {
+    "solid" : "srgb:0.07000,0.07000,0.07000,1.00000"
+  },
+  "groups" : [
+    {
+      "layers" : [
+        {
+          "image-name" : "logo.png",
+          "name" : "logo",
+          "position" : {
+            "scale" : 1.8,
+            "translation-in-points" : [0, 0]
+          }
+        }
+      ]
+    }
+  ],
+  "supported-platforms" : {
+    "squares" : [
+      "macOS"
+    ]
+  }
+}

macos/App/Assets.xcassets/AppIcon.appiconset/Contents.json

@@ -1,68 +0,0 @@
-{
-  "images": [
-    {
-      "idiom": "mac",
-      "size": "16x16",
-      "scale": "1x",
-      "filename": "icon_16.png"
-    },
-    {
-      "idiom": "mac",
-      "size": "16x16",
-      "scale": "2x",
-      "filename": "icon_32.png"
-    },
-    {
-      "idiom": "mac",
-      "size": "32x32",
-      "scale": "1x",
-      "filename": "icon_32.png"
-    },
-    {
-      "idiom": "mac",
-      "size": "32x32",
-      "scale": "2x",
-      "filename": "icon_64.png"
-    },
-    {
-      "idiom": "mac",
-      "size": "128x128",
-      "scale": "1x",
-      "filename": "icon_128.png"
-    },
-    {
-      "idiom": "mac",
-      "size": "128x128",
-      "scale": "2x",
-      "filename": "icon_256.png"
-    },
-    {
-      "idiom": "mac",
-      "size": "256x256",
-      "scale": "1x",
-      "filename": "icon_256.png"
-    },
-    {
-      "idiom": "mac",
-      "size": "256x256",
-      "scale": "2x",
-      "filename": "icon_512.png"
-    },
-    {
-      "idiom": "mac",
-      "size": "512x512",
-      "scale": "1x",
-      "filename": "icon_512.png"
-    },
-    {
-      "idiom": "mac",
-      "size": "512x512",
-      "scale": "2x",
-      "filename": "icon_1024.png"
-    }
-  ],
-  "info": {
-    "author": "xcode",
-    "version": 1
-  }
-}