feat(inspect): add support for NGWAF inspect api

Author: zkat

.gitignore

@@ -5,6 +5,7 @@ dist/
 /integration-tests/**/fixtures/**/*.tar.gz
 /integration-tests/**/fixtures/**/fastly.toml
 /integration-tests/**/fixtures/**/*.wasm
+/integration-tests/**/fixtures/**/*.js.map
 
 /runtime/fastly/build-*/
 

documentation/docs/security/inspect.mdx

@@ -0,0 +1,87 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# inspect
+
+The **`inspect()`** function inspects 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.
+    - This parameter is currently required.
+  - `workspace` _: string_
+    - Set a workspace name for the configuration.
+    - This parameter is currently required.
+  - `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:
+
+- `waf_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
+
+```js
+/// <reference types="@fastly/js-compute" />
+
+import { inspect } from "fastly:security";
+
+async function app(event) {
+  const res = inspect(event.request, {
+    corp: "mycorp",
+    workspace: "myws"
+  });
+  switch (res.verdict) {
+    case "allow":
+      return await fetch(event.request);
+    case "block":
+      return new Response("Request Blocked", { status: 400 });
+    case "unauthorized":
+      return new Response("Unauthorized", { status: 401 });
+    default:
+      return new Response("idk", { status: 500 });
+  }
+}
+
+addEventListener("fetch", (event) => event.respondWith(app(event)));
+```

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,36 @@
+/* eslint-env serviceworker */
+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);
+  strictEqual(result.verdict, 'allow');
+  strictEqual(result.waf_response, 200);
+  strictEqual(Array.isArray(result.tags), true);
+  strictEqual(typeof result.decision_ms, 'number');
+  assert(result.decision_ms >= 0, true);
+});

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": ["viceroy"]
+  },
+  "GET /fastly/security/inspect/basic": {
+    "environments": ["viceroy"]
   }
 }

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

@@ -169,6 +169,115 @@ 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;
+  }
+  JS::RootedObject request(cx, &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);
+
+  host_api::HostString corp_str;
+  JS::RootedValue corp_val(cx);
+
+  host_api::HostString workspace_str;
+  JS::RootedValue workspace_val(cx);
+
+  host_api::HostString override_client_ip_str;
+  JS::RootedValue override_client_ip_val(cx);
+  alignas(struct in6_addr) uint8_t octets[sizeof(struct in6_addr)];
+
+  if (options_obj != nullptr) {
+    if (JS_GetProperty(cx, options_obj, "corp", &corp_val)) {
+      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;
+        }
+        inspect_options.corp_len = corp_str.size();
+        inspect_options.corp = std::move(corp_str.begin());
+      }
+    }
+
+    if (JS_GetProperty(cx, options_obj, "workspace", &workspace_val)) {
+      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;
+        }
+        inspect_options.workspace_len = workspace_str.size();
+        inspect_options.workspace = std::move(workspace_str.begin());
+      }
+    }
+
+    if (JS_GetProperty(cx, options_obj, "overrideClientIp", &override_client_ip_val)) {
+      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;
+        }
+
+        if (inet_pton(format, override_client_ip_str.begin(), &octets) != 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 = reinterpret_cast<const char *>(&octets);
+      }
+    }
+  }
+
+  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 +726,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 +868,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/builtins/fastly.cpp

@@ -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.h

@@ -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);

runtime/fastly/host-api/fastly.h

@@ -2265,6 +2265,43 @@ Result<HostString> HttpReq::get_suggested_cache_key() const {
   return Result<HostString>::ok(make_host_string(str));
 }
 
+Result<HostString> Request::inspect(const InspectOptions *config) {
+  TRACE_CALL()
+  Result<HostString> res;
+  uint32_t inspect_opts_mask{0};
+  fastly::fastly_host_http_inspect_options opts;
+
+  if (config->corp != nullptr) {
+    inspect_opts_mask |= FASTLY_HOST_HTTP_REQ_INSPECT_CONFIG_OPTIONS_MASK_CORP;
+    opts.corp = config->corp;
+    opts.corp_len = config->corp_len;
+  }
+
+  if (config->workspace != nullptr) {
+    inspect_opts_mask |= FASTLY_HOST_HTTP_REQ_INSPECT_CONFIG_OPTIONS_MASK_WORKSPACE;
+    opts.workspace = config->workspace;
+    opts.workspace_len = config->workspace_len;
+  }
+
+  if (config->override_client_ip_ptr != nullptr) {
+    inspect_opts_mask |= FASTLY_HOST_HTTP_REQ_INSPECT_CONFIG_OPTIONS_MASK_OVERRIDE_CLIENT_IP;
+    opts.override_client_ip_ptr = config->override_client_ip_ptr;
+    opts.override_client_ip_len = config->override_client_ip_len;
+  }
+
+  fastly::fastly_host_error err;
+  fastly::fastly_world_string ret;
+  ret.ptr = static_cast<uint8_t *>(cabi_malloc(HOSTCALL_BUFFER_LEN, 4));
+  if (!convert_result(fastly::req_inspect(this->req.handle, this->body.handle, inspect_opts_mask,
+                                          &opts, ret.ptr, HOSTCALL_BUFFER_LEN, &ret.len),
+                      &err)) {
+    res.emplace_err(err);
+  } else {
+    res.emplace(make_host_string(ret));
+  }
+  return res;
+}
+
 // HttpCacheEntry method implementations
 Result<HttpCacheEntry> HttpCacheEntry::lookup(const HttpReq &req, std::span<uint8_t> override_key) {
   TRACE_CALL()