{"id":13788849,"url":"https://github.com/mk-fg/nginx-stat-check","last_synced_at":"2026-02-17T11:01:31.664Z","repository":{"id":144996255,"uuid":"235103584","full_name":"mk-fg/nginx-stat-check","owner":"mk-fg","description":"Simple nginx module that returns 403 if stat() of specified path succeeds","archived":false,"fork":false,"pushed_at":"2025-02-22T09:56:44.000Z","size":10,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-23T22:43:24.332Z","etag":null,"topics":["access-control","blacklisting","bots","module","nginx"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"wtfpl","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mk-fg.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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,"zenodo":null}},"created_at":"2020-01-20T13:07:01.000Z","updated_at":"2025-02-22T09:56:48.000Z","dependencies_parsed_at":"2025-04-23T22:41:14.618Z","dependency_job_id":"89bae3e9-d396-44ad-a7bc-b434d9e13d68","html_url":"https://github.com/mk-fg/nginx-stat-check","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mk-fg/nginx-stat-check","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Fnginx-stat-check","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Fnginx-stat-check/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Fnginx-stat-check/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Fnginx-stat-check/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mk-fg","download_url":"https://codeload.github.com/mk-fg/nginx-stat-check/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Fnginx-stat-check/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29541119,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T08:11:05.436Z","status":"ssl_error","status_checked_at":"2026-02-17T08:09:38.860Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["access-control","blacklisting","bots","module","nginx"],"created_at":"2024-08-03T21:00:54.632Z","updated_at":"2026-02-17T11:01:31.649Z","avatar_url":"https://github.com/mk-fg.png","language":"C","funding_links":[],"categories":["Third Party Modules"],"sub_categories":["C Modules"],"readme":"ngx_http_stat_check module\n==========================\n\n.. contents::\n  :backlinks: none\n\nAlt-URLs for this repository:\n\n- https://github.com/mk-fg/nginx-stat-check\n- https://codeberg.org/mk-fg/nginx-stat-check\n- https://fraggod.net/code/git/nginx-stat-check\n\n\nDescription\n-----------\n\nSimple nginx_ module that returns HTTP \"403 Forbidden\" error if `stat()`_\nof specified path succeeds.\n\nIntended use is trivial djbdns-style filesystem-db blacklisting by any\n`nginx variable`_ set on request, for example $remote_addr (think fail2ban).\n\n.. _nginx: https://www.nginx.com/\n.. _stat(): https://en.wikipedia.org/wiki/Stat_(system_call)\n.. _nginx variable: https://nginx.org/en/docs/varindex.html\n\n\nBuild / install\n---------------\n\nModule requires source code for same-ish nginx version as it will be loaded by::\n\n  % ver=1.16.1 # make sure it matches installed nginx version\n  % curl -L https://nginx.org/download/nginx-$ver.tar.gz | tar -xz\n\n  % cd nginx-$ver\n  % test -e Makefile || ./configure --with-compat --add-dynamic-module=..\n  % make modules\n\n  % cd objs\n  % install -m755 -t /usr/lib/nginx/modules/ ngx_http_stat_check.so\n\nRe-run two last bits to rebuild after any code or nginx updates.\n\n\nUsage\n-----\n\nModule adds single \"stat_check\" directive, which takes path template\nas its one argument, and is only allowed in \"location\" context.\n\n::\n\n  load_module /usr/lib/nginx/modules/ngx_http_stat_check.so;\n  ...\n  location /my-files {\n    alias /srv/www/my-files;\n    autoindex on;\n    stat_check /tmp/blacklist/$remote_addr;\n  }\n\nThis will have module run single stat() call for every request, checking if\n\"/tmp/blacklist/$remote_addr\" path exists, returning \"403 Forbidden\" if that's\nthe case.\n\nFor example, if request comes from 1.2.3.4 IP address (be sure to `check docs on\nremote_addr first!`_), path /tmp/blacklist/1.2.3.4 will be checked, and if\nexists, any request to /my-files location will be denied for this client.\n\nAny other nginx variables can be used in the same way, including regexp-matched\npath fragments, mapped or custom-set values.\n\n.. _check docs on remote_addr first!: https://nginx.org/en/docs/http/ngx_http_core_module.html#var_remote_addr\n\n\nWhy it exists\n-------------\n\nIntended use is blocking access dynamically to various unwanted http spam and\nbots on relatively idle servers (see also `nginx-access-log-stat-block script`_).\n\nRegular nginx configuration does not allow that, as it lacks any kind of\nexternal/dynamic configuration.\n\nIt is however available in a `premium Nginx Plus version via \"keyval\" module`_\nvia JSON API, and maybe will be merged into open version someday, so be sure to\ncheck for that first.\n\nWhile I don't think that extra per-request stat() might make a difference\nperformance-wise, this module is not intended or tested for/in any kind of\nhigh-load environments, and might not be suitable against something like a\nDDoS attack - use CloudFlare, firewalls, Nginx Plus functionality or whatever\ndedicated solutions for that.\n\nSee `\"Dynamic blacklisting configuration\" blog post here`_ for even more info.\n\n.. _nginx-access-log-stat-block script: https://github.com/mk-fg/fgtk#nginx-access-log-stat-block\n.. _premium Nginx Plus version via \"keyval\" module: https://docs.nginx.com/nginx/admin-guide/security-controls/blacklisting-ip-addresses/\n.. _\"Dynamic blacklisting configuration\" blog post here: https://blog.fraggod.net/2020/01/03/dynamic-blacklisting-configuration-for-nginx-access-via-custom-module.html\n\n\nRoom for improvement\n--------------------\n\nItems here look like an obvious improvements, mostly for flexibility and\nunlocking new vast use-cases, but doubt I'll get to these unless will need it myself.\n\n- Make HTTP error page configurable, e.g. like =403 in try_files directive.\n\n- Separate more complex directive that respects \"root\" and \"alias\" paths.\n\n- Option to invert exists/missing logic for returning errors.\n\n- Allow to specify $uri or @named-location to jump to on this condition.\n\n- Allow/use hashed paths to avoid storing plaintext request info and to allow\n  easy nesting of these on filesystem (instead of having all nodes in one dir).\n\n\nLinks\n-----\n\n- https://github.com/mk-fg/fgtk#nginx-access-log-stat-block\n\n  Script to use blocking by $remote_addr with access_log from some honeypot-trap\n  URL to block misbehaving bots that violate robots.txt and similar restrictions.\n\n- https://github.com/agile6v/awesome-nginx#third-party-modules\n- https://github.com/Vasfed/nginx_ipset_blacklist/\n- https://github.com/rryqszq4/ngx_sqlite/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmk-fg%2Fnginx-stat-check","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmk-fg%2Fnginx-stat-check","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmk-fg%2Fnginx-stat-check/lists"}