feat(inspect): add support for NGWAF inspect api

Author: zkat

documentation/docs/security/inspect.mdx

@@ -0,0 +1,62 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# inspect
+
+The **`inspect()`** inspect a request using the [Fastly Next-Gen WAF](https://docs.fastly.com/en/ngwaf/).
+
+## Syntax
+
+```js
+inspect(request, config);
+```
+
+### Parameters
+
+- `request` _: Request_
+  - The Request to get a WAF determination for.
+- `config` _: object_
+  - `corp` _: string_
+    - Set a corp name for the configuration.
+  - `workspace` _: string_
+    - Set a workspace name for the configuration.
+  - `overrideClientIp` _: string_
+    - Specify an explicit client IP address to inspect.
+    - By default, `inspect` will use the IP address that made the request to the
+      running Compute service, but you may want to use a different IP when
+      service chaining or if requests are proxied from outside of Fastly’s
+      network.
+
+### Return value
+
+Returns an `Object` with the `inspect` response, with the following fields:
+
+- `response` _: number_
+  - Security status code.
+  
+- `redirect_url` _: string | null_
+  - A redirect URL returned from Security.
+
+- `tags` _: string[]_
+  - Tags returned by Security.
+
+- `verdict` _: string_
+  - The outcome of inspecting a request with Security. It can be one of the following:
+    - `"allow"`
+      - Security indicated that this request is allowed.
+    - `"block"`
+      - Security indicated that this request should be blocked.
+    - `"unauthorized"`
+      - Security indicated that this service is not authorized to inspect a request.
+    - Other verdicts may be returned but not currently documented.
+
+- `decision_ms` _: number_
+  - How long Security spent determining its verdict, in milliseconds.
+  
+## Examples
+
+<!-- TODO(@zkat): Write out an example -->

integration-tests/js-compute/fixtures/app/__input_bundled.js.map

@@ -46,6 +46,7 @@ import './response-json.js';
 import './response-redirect.js';
 import './response.js';
 import './secret-store.js';
+import './security.js';
 import './server.js';
 import './shielding.js';
 import './tee.js';

integration-tests/js-compute/fixtures/app/src/index.js

@@ -0,0 +1,37 @@
+/* eslint-env serviceworker */
+/* global fastly */
+import { assert, assertThrows, strictEqual } from './assertions.js';
+import { inspect } from 'fastly:security';
+import { routes } from './routes.js';
+
+routes.set('/fastly/security/inspect/invalid-config', () => {
+  const req = new Request('https://example.com');
+  assertThrows(() => {
+    inspect(req);
+  });
+  assertThrows(() => {
+    inspect(req, {
+      corp: 'test',
+    });
+  });
+  assertThrows(() => {
+    inspect(req, {
+      workspace: 'test',
+    });
+  });
+});
+
+routes.set('/fastly/security/inspect/basic', () => {
+  const req = new Request('https://example.com');
+  const config = {
+    corp: 'test',
+    workspace: 'test',
+    overrideClientIp: '10.10.10.10',
+  };
+  const result = inspect(req, config);
+  assert(strictEqual(result.verdict, 'allow'));
+  assert(strictEqual(result.response, 123)); // TODO(@zkat): What should this be?
+  assert(Array.isArray(result.tags));
+  assert(strictEqual(typeof result.decision_ms, 'number'));
+  assert(result.decision_ms >= 0);
+});

integration-tests/js-compute/fixtures/app/src/security.js

@@ -3139,5 +3139,11 @@
   },
   "GET /shielding/invalid-shield": {
     "environments": ["compute"]
+  },
+  "GET /fastly/security/inspect/invalid-config": {
+    "environments": ["compute"]
+  },
+  "GET /fastly/security/inspect/basic": {
+    "environments": ["compute"]
   }
 }

integration-tests/js-compute/fixtures/app/tests.json

@@ -3,6 +3,8 @@ cmake_minimum_required(VERSION 3.27)
 #FIXME(1243)
 file(COPY "${CMAKE_CURRENT_SOURCE_DIR}/../rust-toolchain.toml" DESTINATION "${CMAKE_CURRENT_SOURCE_DIR}/../StarlingMonkey")
 
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
 include("../StarlingMonkey/cmake/add_as_subproject.cmake")
 
 add_builtin(

package-lock.json

@@ -169,6 +169,121 @@ bool Fastly::getGeolocationForIpAddress(JSContext *cx, unsigned argc, JS::Value
   return JS_ParseJSON(cx, geo_info_str, args.rval());
 }
 
+bool Fastly::inspect(JSContext *cx, unsigned argc, JS::Value *vp) {
+  JS::CallArgs args = CallArgsFromVp(argc, vp);
+  REQUEST_HANDLER_ONLY("fastly.inspect");
+  if (!args.requireAtLeast(cx, "fastly.inspect", 1)) {
+    return false;
+  }
+
+  auto request_value = args.get(0);
+  if (!Request::is_instance(request_value)) {
+    JS_ReportErrorUTF8(cx, "inspect: request parameter must be an instance of Request");
+    return false;
+  }
+  auto request = &request_value.toObject();
+  auto req{Request::request_handle(request)};
+  auto bod{RequestOrResponse::body_handle(request)};
+
+  auto options_value = args.get(1);
+  JS::RootedObject options_obj(cx, options_value.isObject() ? &options_value.toObject() : nullptr);
+
+  host_api::InspectOptions inspect_options(req.handle, bod.handle);
+
+  if (options_obj != nullptr) {
+    host_api::HostString corp_str;
+    JS::RootedValue corp_val(cx);
+    if (!JS_GetProperty(cx, options_obj, "corp", &corp_val)) {
+      return false;
+    }
+    if (!corp_val.isNullOrUndefined()) {
+      if (!corp_val.isString()) {
+        api::throw_error(cx, api::Errors::TypeError, "fastly.inspect", "corp", "be a string");
+        return false;
+      }
+      corp_str = core::encode(cx, corp_val);
+      if (!corp_str) {
+        return false;
+      }
+      std::optional<std::string_view> corp = corp_str;
+      if (corp) {
+        inspect_options.corp_len = corp->length();
+        inspect_options.corp = std::move(corp->data());
+      }
+    }
+
+    host_api::HostString workspace_str;
+    JS::RootedValue workspace_val(cx);
+    if (!JS_GetProperty(cx, options_obj, "workspace", &workspace_val)) {
+      return false;
+    }
+    if (!workspace_val.isNullOrUndefined()) {
+      if (!workspace_val.isString()) {
+        api::throw_error(cx, api::Errors::TypeError, "fastly.inspect", "workspace", "be a string");
+        return false;
+      }
+      workspace_str = core::encode(cx, workspace_val);
+      if (!workspace_str) {
+        return false;
+      }
+      std::optional<std::string_view> workspace = workspace_str;
+      if (workspace) {
+        inspect_options.workspace_len = workspace->length();
+        inspect_options.workspace = std::move(workspace->data());
+      }
+    }
+
+    host_api::HostString override_client_ip_str;
+    JS::RootedValue override_client_ip_val(cx);
+    std::vector<char> octets;
+    if (!JS_GetProperty(cx, options_obj, "overrideClientIp", &override_client_ip_val)) {
+      return false;
+    }
+    if (!override_client_ip_val.isNullOrUndefined()) {
+      if (!override_client_ip_val.isString()) {
+        api::throw_error(cx, api::Errors::TypeError, "fastly.inspect", "overrideClientIp",
+                         "be a string");
+        return false;
+      }
+      override_client_ip_str = core::encode(cx, override_client_ip_val);
+      if (!override_client_ip_str) {
+        return false;
+      }
+
+      // TODO: Remove all of this and rely on the host for validation as the hostcall only takes one
+      // user-supplied parameter
+      int format = AF_INET;
+      size_t octets_len = 4;
+      if (std::find(override_client_ip_str.begin(), override_client_ip_str.end(), ':') !=
+          override_client_ip_str.end()) {
+        format = AF_INET6;
+        octets_len = 16;
+      }
+
+      octets.reserve(sizeof(struct in6_addr));
+      if (inet_pton(format, override_client_ip_str.begin(), octets.data()) != 1) {
+        api::throw_error(cx, api::Errors::TypeError, "fastly.inspect", "overrideClientIp",
+                         "be a valid IP address");
+        return false;
+      }
+      inspect_options.override_client_ip_len = octets_len;
+      inspect_options.override_client_ip_ptr = octets.data();
+    }
+  }
+
+  host_api::Request host_request{req, bod};
+  auto res = host_request.inspect(&inspect_options);
+  if (auto *err = res.to_err()) {
+    HANDLE_ERROR(cx, *err);
+    return false;
+  }
+
+  auto ret{std::move(res.unwrap())};
+
+  JS::RootedString js_str(cx, JS_NewStringCopyUTF8N(cx, JS::UTF8Chars(ret.ptr.release(), ret.len)));
+  return JS_ParseJSON(cx, js_str, args.rval());
+}
+
 // TODO(performance): consider allowing logger creation during initialization, but then throw
 // when trying to log.
 // https://github.com/fastly/js-compute-runtime/issues/225
@@ -617,6 +732,7 @@ bool install(api::Engine *engine) {
       JS_FN("enableDebugLogging", Fastly::enableDebugLogging, 1, JSPROP_ENUMERATE),
       JS_FN("debugLog", debugLog, 1, JSPROP_ENUMERATE),
       JS_FN("getGeolocationForIpAddress", Fastly::getGeolocationForIpAddress, 1, JSPROP_ENUMERATE),
+      JS_FN("inspect", Fastly::inspect, 1, JSPROP_ENUMERATE),
       JS_FN("getLogger", Fastly::getLogger, 1, JSPROP_ENUMERATE),
       JS_FN("includeBytes", Fastly::includeBytes, 1, JSPROP_ENUMERATE),
       JS_FN("createFanoutHandoff", Fastly::createFanoutHandoff, 2, JSPROP_ENUMERATE),
@@ -758,6 +874,21 @@ bool install(api::Engine *engine) {
   if (!engine->define_builtin_module("fastly:fanout", fanout_val)) {
     return false;
   }
+
+  // fastly:security
+  RootedValue inspect_val(engine->cx());
+  if (!JS_GetProperty(engine->cx(), fastly, "inspect", &inspect_val)) {
+    return false;
+  }
+  RootedObject security_builtin(engine->cx(), JS_NewObject(engine->cx(), nullptr));
+  RootedValue security_builtin_val(engine->cx(), JS::ObjectValue(*security_builtin));
+  if (!JS_SetProperty(engine->cx(), security_builtin, "inspect", inspect_val)) {
+    return false;
+  }
+  if (!engine->define_builtin_module("fastly:security", security_builtin_val)) {
+    return false;
+  }
+
   // fastly:websocket
   RootedObject websocket(engine->cx(), JS_NewObject(engine->cx(), nullptr));
   RootedValue websocket_val(engine->cx(), JS::ObjectValue(*websocket));

runtime/fastly/CMakeLists.txt

@@ -60,6 +60,7 @@ class Fastly : public builtins::BuiltinNoConstructor<Fastly> {
   static bool defaultBackend_set(JSContext *cx, unsigned argc, JS::Value *vp);
   static bool allowDynamicBackends_get(JSContext *cx, unsigned argc, JS::Value *vp);
   static bool allowDynamicBackends_set(JSContext *cx, unsigned argc, JS::Value *vp);
+  static bool inspect(JSContext *cx, unsigned argc, JS::Value *vp);
 };
 
 JS::Result<std::tuple<JS::UniqueChars, size_t>> convertBodyInit(JSContext *cx,

runtime/fastly/builtins/fastly.cpp

@@ -39,6 +39,15 @@ typedef struct fastly_host_http_response {
   uint32_t f1;
 } fastly_host_http_response;
 
+typedef struct fastly_host_http_inspect_options {
+  const char *corp;
+  uint32_t corp_len;
+  const char *workspace;
+  uint32_t workspace_len;
+  const char *override_client_ip_ptr;
+  uint32_t override_client_ip_len;
+} fastly_host_http_inspect_options;
+
 typedef fastly_host_http_response fastly_world_tuple2_handle_handle;
 
 #define WASM_IMPORT(module, name) __attribute__((import_module(module), import_name(name)))
@@ -265,6 +274,13 @@ typedef enum BodyWriteEnd {
 #define CACHE_OVERRIDE_STALE_WHILE_REVALIDATE (1u << 2)
 #define CACHE_OVERRIDE_PCI (1u << 3)
 
+typedef uint32_t req_inspect_config_options_mask;
+
+#define FASTLY_HOST_HTTP_REQ_INSPECT_CONFIG_OPTIONS_MASK_RESERVED (1 << 0);
+#define FASTLY_HOST_HTTP_REQ_INSPECT_CONFIG_OPTIONS_MASK_CORP (1 << 1);
+#define FASTLY_HOST_HTTP_REQ_INSPECT_CONFIG_OPTIONS_MASK_WORKSPACE (1 << 2);
+#define FASTLY_HOST_HTTP_REQ_INSPECT_CONFIG_OPTIONS_MASK_OVERRIDE_CLIENT_IP (1 << 3);
+
 WASM_IMPORT("fastly_abi", "init")
 int init(uint64_t abi_version);
 
@@ -629,6 +645,12 @@ int req_pending_req_wait_v2(uint32_t req_handle,
                             fastly_host_http_send_error_detail *send_error_detail,
                             uint32_t *resp_handle_out, uint32_t *resp_body_handle_out);
 
+WASM_IMPORT("fastly_http_req", "inspect")
+int req_inspect(uint32_t req_handle, uint32_t body_handle,
+                req_inspect_config_options_mask config_options_mask,
+                fastly_host_http_inspect_options *config, uint8_t *inspect_res_buf,
+                uint32_t inspect_res_buf_len, size_t *nwritten_out);
+
 // Module fastly_http_resp
 WASM_IMPORT("fastly_http_resp", "new")
 int resp_new(uint32_t *resp_handle_out);