{"id":13617750,"url":"https://github.com/dylibso/modsurfer","last_synced_at":"2025-08-20T05:04:37.210Z","repository":{"id":65731070,"uuid":"557662431","full_name":"dylibso/modsurfer","owner":"dylibso","description":"Devtools to validate, audit and investigate WebAssembly binaries.","archived":false,"fork":false,"pushed_at":"2024-04-15T23:43:29.000Z","size":16215,"stargazers_count":123,"open_issues_count":6,"forks_count":5,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-30T22:04:09.008Z","etag":null,"topics":["binary-scan","cli","debug","diagnostics","observability","security","system-of-record","wasm","webassembly"],"latest_commit_sha":null,"homepage":"https://dev.dylibso.com/docs/modsurfer/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dylibso.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-26T04:13:41.000Z","updated_at":"2025-04-06T07:13:47.000Z","dependencies_parsed_at":"2024-01-06T01:01:00.442Z","dependency_job_id":"9b195271-d109-4c78-83ec-095c2c23a63c","html_url":"https://github.com/dylibso/modsurfer","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/dylibso/modsurfer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylibso%2Fmodsurfer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylibso%2Fmodsurfer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylibso%2Fmodsurfer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylibso%2Fmodsurfer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dylibso","download_url":"https://codeload.github.com/dylibso/modsurfer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylibso%2Fmodsurfer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271268705,"owners_count":24730023,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-20T02:00:09.606Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binary-scan","cli","debug","diagnostics","observability","security","system-of-record","wasm","webassembly"],"created_at":"2024-08-01T20:01:47.368Z","updated_at":"2025-08-20T05:04:37.183Z","avatar_url":"https://github.com/dylibso.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# Modsurfer\n\n![Modsurfer](.github/img/modsurfer-logo.svg)\n\n\u003e ### Modsurfer provides ops \u0026 dev teams with a system of record + diagnostics application to search, browse, and investigate modules.\n\nFor developers, SRE, DevOps, and engineering leaders: understand what the\nWebAssembly in your system is all about. Modsurfer provides critical information\nabout WebAssembly code through a handy GUI, or directly at your fingertips via\nour CLI.\n\nUse Modsurfer for:\n\n- **at-a-glance insights** into WebAssembly module data (code size \u0026 complexity,\n  imports/exports \u0026 more)\n- **search for details** about modules (hash, ID, function names, strings,\n  namespaces, errors \u0026 more)\n- **off-the-shelf** System of Record: easily audit and track all the WebAssembly\n  code in your stack\n- **debug \u0026 triage issues** otherwise difficult to pinpoint in opaque\n  WebAssembly format\n\n### Modsurfer Desktop Application\n\nThe desktop application is **free** and available to download from\n[Dylibso](https://dylibso.com/downloads/modsurfer), and is a useful debugging,\nvisibility, and diagnostics tool for anyone working with WebAssembly.\n\n![Modsurfer](https://dylibso.com/assets/modsurfer-product-desktop.png)\n\n### Enterprise\n\nIf you're running WebAssmebly code in production, you may be interested in using\nthe Enterprise version of Modsurfer. Please reach out to us at\n[support@dylibso.com](mailto:support@dylibso.com) and we'll be happy to get you\nmore information about licensing and self-managed deployment requirements.\n\n---\n\n## In this repository\n\nThis is a collection of Rust crates and other code that is used for a variety of\nModsurfer-related purposes. You can find a list and description of these below.\n\n## `cli`\n\nThe Modsurfer CLI provides two primary functions:\n\n1. HTTP Client to interace with Modsurfer (either the desktop app, or your\n   Enterprise deployment)\n2. Validation to ensure that WebAssembly binaries:\n\n- are compatible with various host ABIs\n- have no known security issues / comply with your policy\n- meet the runtime requirements in terms of size and code complexity (RAM/CPU\n  limits, etc)\n\n### Download the CLI\n\nModsurfer CLI can be downloaded via:\n\n- the latest\n  [GitHub Release](https://github.com/dylibso/modsurfer/releases/latest)\n- the GitHub container registry (for Docker environments)\n  - `docker pull ghcr.io/dylibso/modsurfer:latest`\n\n### Validate WebAssembly Modules\n\nModsurfer CLI provides a novel feature to process and validate a WebAssembly\nmodule based on policy/properties of the module that you define. In a\n\"checkfile\" (see the `mod.yaml` below), declare certain properties of a\nWebAssembly module and Modsurfer will verify that they are true, or report which\nproperties of your binary are invalid.\n\n```yaml\nvalidate:\n  # simply require that a module can have WASI functionality or not\n  allow_wasi: false\n  \n  # ensure that various imports and exports are included/exlcuded such that a module\n  # will run properly in any host environment\n  imports:\n    include:\n      # ensure these named functions are in the imports of this module  \n      - log_message\n      - proc_exit\n      \n      # further specify the function beyond its name \n      - namespace: env\n        name: http_get\n        params: [I32, I32]\n        results: [I32]\n    exclude: \n      - fd_write\n    namespace:\n      include:\n        - env\n      exclude:\n        # phasing out old APIs? exclude these from acceptable namespaces/module names\n        - some_future_deprecated_module_name\n        - wasi_snapshot_preview1\n\n  exports: \n    # only want exactly 2 functions exported: `_start` and `bar` for the host to call:\n    max: 2\n    # secure your modules by ensuring that there is no superfluous functionality hidden inside a binary\n    include:\n      - _start\n      - name: bar\n        params: []\n        results: [I32, I32, I32, I32]\n    # and/or ensuring no unwanted functions to be exported.\n    exclude:\n      - name: init\n        results: []\n      - foo\n\n  # use a human-readable module size to prevent overly large binaries from running in your environment\n  size:\n    max: 4MB\n\n  # our Cyclomatic Complexity analysis can help prevent risk of CPU exhaustion from deteriorating \n  # your user experience and slowing down your system\n  # (override these low, medium, high optional values with environment variables $MODSURFER_RISK_{LOW,MEDIUM,HIGH})\n  complexity:\n    max_risk: low\n```\n\nYou can also point to a remote check file to track up-to-date requirements:\n\n```yaml\nvalidate:\n  url: https://raw.githubusercontent.com/fermyon/spin/main/tools/modsurfer/http/mod.yaml\n```\n\n### Usage\n\nModsurfer runs validation tests on compiled .wasm binaries. It uses a\n\"checkfile\" to compare with the contents of a .wasm binary. The `modsurfer` CLI\nprovides\n[a number of commands](https://dev.dylib.so/docs/modsurfer/cli#commands) to\ncreate and use a checkfile, as well as to interact as a client to a remote\nservice that stores and organizes your WebAssembly modules available over HTTP\n(via [this `protobuf` API](./proto/v1/api.proto)).\n\n##### To create a \"checkfile\" (passed to `-c`), run the `generate` command:\n\n```\nmodsurfer generate -p path/to/my.wasm -o mod.yaml\n```\n\n\u003e **NOTE:** this checkfile will be very restrictive, and you likely want to edit\n\u003e it to fit less (or more) restricted environments.\n\n##### To run validation, you can use our [GitHub Action](https://github.com/dylibso/modsurfer-validate-action), or call the `validate` command directly:\n\n```\nmodsurfer validate -p path/to/my.wasm -c path/to/mod.yaml\n```\n\nIf any of the restrictions or expectations declared in your checkfile are not\nsatisfied, Modsurfer will report them:\n\n```\n┌────────┬──────────────────────────────────────────────────┬──────────┬──────────┬───────────────────┬────────────┐\n│ Status │ Property                                         │ Expected │ Actual   │ Classification    │ Severity   │\n╞════════╪══════════════════════════════════════════════════╪══════════╪══════════╪═══════════════════╪════════════╡\n│ FAIL   │ allow_wasi                                       │ false    │ true     │ ABI Compatibility │ |||||||||| │\n├────────┼──────────────────────────────────────────────────┼──────────┼──────────┼───────────────────┼────────────┤\n│ FAIL   │ complexity.max_risk                              │ \u003c= low   │ medium   │ Resource Limit    │ |          │\n├────────┼──────────────────────────────────────────────────┼──────────┼──────────┼───────────────────┼────────────┤\n│ FAIL   │ exports.exclude.main                             │ excluded │ included │ Security          │ |||||      │\n├────────┼──────────────────────────────────────────────────┼──────────┼──────────┼───────────────────┼────────────┤\n│ FAIL   │ exports.include.bar                              │ included │ excluded │ ABI Compatibility │ |||||||||| │\n├────────┼──────────────────────────────────────────────────┼──────────┼──────────┼───────────────────┼────────────┤\n│ FAIL   │ exports.max                                      │ \u003c= 100   │ 151      │ Security          │ ||||||     │\n├────────┼──────────────────────────────────────────────────┼──────────┼──────────┼───────────────────┼────────────┤\n│ FAIL   │ imports.include.http_get                         │ included │ excluded │ ABI Compatibility │ ||||||||   │\n├────────┼──────────────────────────────────────────────────┼──────────┼──────────┼───────────────────┼────────────┤\n│ FAIL   │ imports.include.log_message                      │ included │ excluded │ ABI Compatibility │ ||||||||   │\n├────────┼──────────────────────────────────────────────────┼──────────┼──────────┼───────────────────┼────────────┤\n│ FAIL   │ imports.namespace.exclude.wasi_snapshot_preview1 │ excluded │ included │ ABI Compatibility │ |||||||||| │\n├────────┼──────────────────────────────────────────────────┼──────────┼──────────┼───────────────────┼────────────┤\n│ FAIL   │ imports.namespace.include.env                    │ included │ excluded │ ABI Compatibility │ ||||||||   │\n├────────┼──────────────────────────────────────────────────┼──────────┼──────────┼───────────────────┼────────────┤\n│ FAIL   │ size.max                                         │ \u003c= 4MB   │ 4.4 MiB  │ Resource Limit    │ |          │\n└────────┴──────────────────────────────────────────────────┴──────────┴──────────┴───────────────────┴────────────┘\n```\n\n\u003e **NOTE**: convert this table into JSON with the `--output-format json` option,\n\u003e supported by the `validate` command and many others.\n\nFind more information about the CLI in its dedicated [README](./cli/README.md),\nor download the tool and run `modsurfer -h`.\n\n### Validating platform-specific compatibility\n\nBefore running or integrating a WebAssembly module on your platform (Emscripten,\nExtism, Fastly, Shopify, Spin, Suborbital, wasmCloud, Workers)\n\n#### Contributing\n\n##### Testing the CLI\n\nFrom the root of the repo, run the following to see a basic validation report:\n\n- `make test-cli`\n- `make empty-cli`\n- `make unknown-cli`\n\n`test/` contains a `mod.yaml`, which declares expected properties of a\nWebAssembly module, as well as a `spidermonkey.wasm` file to use as example\ninput to use for the validation. `wasm/` contains a set of WebAssembly binaries\ndownloaded from the [`wapm`](https://wapm.io) package manager used for analysis\nand testing.\n\n---\n\n### `proto` Protobuf definitions and libraries\n\nThis directory contains the Protobuf definitions for the types used in the API.\nMessages have various levels of documentation as well as endpoints if they are\nrequest types. Use the `api.proto` to generate a language client if you'd like\nto interact with Modsurfer API programmatically from your application.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdylibso%2Fmodsurfer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdylibso%2Fmodsurfer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdylibso%2Fmodsurfer/lists"}