{"id":28766111,"url":"https://github.com/mdn/mdn-http-observatory","last_synced_at":"2026-04-14T20:01:06.120Z","repository":{"id":246065772,"uuid":"819918640","full_name":"mdn/mdn-http-observatory","owner":"mdn","description":"Backend for HTTP Observatory on MDN","archived":false,"fork":false,"pushed_at":"2026-04-14T08:18:53.000Z","size":6007,"stargazers_count":123,"open_issues_count":27,"forks_count":33,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-04-14T10:11:20.119Z","etag":null,"topics":["http","http-headers","mdn","privacy","security","security-tools"],"latest_commit_sha":null,"homepage":"https://developer.mozilla.org/en-US/observatory","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mdn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-06-25T12:43:58.000Z","updated_at":"2026-04-14T09:14:22.000Z","dependencies_parsed_at":"2024-08-26T11:42:32.917Z","dependency_job_id":"d1eea031-150e-4424-b30f-1ce5cac61e7c","html_url":"https://github.com/mdn/mdn-http-observatory","commit_stats":null,"previous_names":["mdn/mdn-http-observatory"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/mdn/mdn-http-observatory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdn%2Fmdn-http-observatory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdn%2Fmdn-http-observatory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdn%2Fmdn-http-observatory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdn%2Fmdn-http-observatory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mdn","download_url":"https://codeload.github.com/mdn/mdn-http-observatory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdn%2Fmdn-http-observatory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31812977,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"ssl_error","status_checked_at":"2026-04-14T18:05:01.765Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["http","http-headers","mdn","privacy","security","security-tools"],"created_at":"2025-06-17T11:41:04.113Z","updated_at":"2026-04-14T20:01:06.107Z","avatar_url":"https://github.com/mdn.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Welcome to Mozilla's HTTP Observatory\n\n[HTTP Observatory](https://developer.mozilla.org/en-US/observatory/) is a service that checks web sites for security-relevant headers. It is hosted by [MDN Web Docs](https://github.com/mdn).\n\n## Getting Started\n\nIf you just want to scan a host, please head over to \u003chttps://developer.mozilla.org/en-US/observatory/\u003e. If you want to\nrun the code locally or on your premises, continue reading.\n\n### Running a simple scan from the command line\n\nUsing npx to install the package, simply run\n\n```sh\nnpx @mdn/mdn-http-observatory mdn.dev\n```\n\nSubpaths like `example.com/path` and port numbers like `example.com:8080/path` are suported.\n\nIf you want to install the package first, use npm to install it globally\n\n```sh\nnpm install --global @mdn/mdn-http-observatory\n```\n\nAfter that, the `mdn-http-observatory-scan` command should be available in your shell. To scan a host, run\n\n```sh\nmdn-http-observatory-scan mdn.dev\n```\n\nYou can pass custom request headers as JSON using the `--headers` option:\n\n```sh\nmdn-http-observatory-scan --headers '{\"X-Custom\": \"value\"}' mdn.dev\n```\n\n**Warning:** Headers will also be sent on unencrypted HTTP requests, even if the host enforces HTTPS. Do not pass sensitive data.\n\nBoth methods return a JSON response of the following form:\n\n```json\n{\n  \"scan\": {\n    \"algorithmVersion\": 4,\n    \"grade\": \"A+\",\n    \"error\": null,\n    \"score\": 105,\n    \"statusCode\": 200,\n    \"testsFailed\": 0,\n    \"testsPassed\": 10,\n    \"testsQuantity\": 10,\n    \"responseHeaders\": {\n      ...\n    }\n  },\n  \"tests\": {\n    \"cross-origin-resource-sharing\": {\n      \"expectation\": \"cross-origin-resource-sharing-not-implemented\",\n      \"pass\": true,\n      \"result\": \"cross-origin-resource-sharing-not-implemented\",\n      \"scoreModifier\": 0,\n      \"data\": null\n    },\n    ...\n  }\n}\n```\n\n### Running a local API server\n\nThis needs a [postgres](https://www.postgresql.org/) database for the API to use as a persistence layer. All scans and results initiated via the API are stored in the database.\n\n#### Configuration\n\nDefault configuration is read from a default `config/config.json` file. See [this file](src/config.js) for a list of possible configuration options.\n\nCreate a configuration file by copying the [`config/config-example.json`](conf/config-example.json) to `config/config.json`.\nPut in your database credentials into `config/config.json`:\n\n```json\n{\n  \"database\": {\n    \"database\": \"observatory\",\n    \"user\": \"postgres\"\n  }\n}\n```\n\nTo initialize the database with the proper tables, use this command to migrate. This is a one-time action, but future code changes\nmight need further database changes, so run this migration every time the code is updated from the repository.\n\n```sh\nnpm run migrate\n```\n\nFinally, start the server by running\n\n```sh\nnpm start\n```\n\nThe server is listening on your local interface on port `8080`. You can check the root path by opening \u003chttp://localhost:8080/\u003e in your browser or `curl` the URL. The server should respond with `Welcome to the MDN Observatory!`.\n\n## JSON API\n\n**Note:** We provide these endpoints on our public deployment of HTTP Observatory at \u003chttps://observatory-api.mdn.mozilla.net/\u003e\n\n### POST `/api/v2/scan`\n\nFor integration in CI pipelines or similar applications, a JSON API endpoint is provided. The request rate is limited to one scan per host per `api.cooldown` (default: One minute) seconds. If exceeded, a cached result will be returned.\n\n#### Query parameters\n\n- `host` hostname (required)\n\n#### Examples\n\n- `POST /api/v2/scan?host=mdn.dev`\n- `POST /api/v2/scan?host=google.com`\n\n#### Result\n\nOn success, a JSON object is returned, structured like this example response:\n\n```json\n{\n  \"id\": 77666718,\n  \"details_url\": \"https://developer.mozilla.org/en-US/observatory/analyze?host=mdn.dev\",\n  \"algorithm_version\": 4,\n  \"scanned_at\": \"2024-08-12T08:20:18.926Z\",\n  \"error\": null,\n  \"grade\": \"A+\",\n  \"score\": 105,\n  \"status_code\": 200,\n  \"tests_failed\": 0,\n  \"tests_passed\": 10,\n  \"tests_quantity\": 10\n}\n```\n\n**Note:** For a full set of details about the host, use the provided link in the `details_url` field.\n\nIf an error occurred, an object like this is returned:\n\n```json\n{\n  \"error\": \"invalid-hostname-lookup\",\n  \"message\": \"some.invalid.hostname.dev cannot be resolved\"\n}\n```\n\n## Migrating from the public V1 API to the V2 API\n\n### Sunset of the V1 API\n\nThe previous iteration of the Observatory JSON API has been deprecated and shut down on October 31, 2024.\n\n### Migrating your application\n\nIf you previously used the Observatory API with some automation or a CI context, the switch from the old `/api/v1/analyze` endpoint to the new `/api/v2/scan` endpoint should be painless:\n\n- Replace all API calls to `POST https://http-observatory.security.mozilla.org/api/v1/analyze?host=\u003cHOST TO SCAN\u003e` with `POST https://observatory-api.mdn.mozilla.net/api/v2/scan?host=\u003cHOST TO SCAN\u003e`\n- Be aware that the complete list of headers has been removed from the response.\n- The POST parameters `rescan` and `hidden` in the POST body have been removed.\n- Remove all other requests from your application, if any. If you need any additional information about your scan, open the URL from the `detail_url` field of the response in your browser.\n- Note that scans are still limited to one every minute per host, otherwise a cached response is returned.\n\n## Contributing\n\nOur project welcomes contributions from any member of our community.\nTo get started contributing, please see our [Contributor Guide](CONTRIBUTING.md).\n\nBy participating in and contributing to our projects and discussions, you acknowledge that you have read and agree to our [Code of Conduct](CODE_OF_CONDUCT.md).\n\n## Communications\n\nIf you have any questions, please reach out to us on [Mozilla Developer Network](https://developer.mozilla.org).\n\n## License\n\nThis project is licensed under the [Mozilla Public License 2.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmdn%2Fmdn-http-observatory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmdn%2Fmdn-http-observatory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmdn%2Fmdn-http-observatory/lists"}