{"id":28178404,"url":"https://github.com/keystroke3/census","last_synced_at":"2025-07-12T15:11:27.483Z","repository":{"id":217573327,"uuid":"743748857","full_name":"keystroke3/census","owner":"keystroke3","description":"Fuzzy search files in your directories with ease","archived":false,"fork":false,"pushed_at":"2025-05-08T23:50:27.000Z","size":15485,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-16T01:12:25.427Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/keystroke3.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":"2024-01-15T22:43:50.000Z","updated_at":"2025-05-08T23:50:31.000Z","dependencies_parsed_at":"2024-04-21T20:07:54.770Z","dependency_job_id":"751ce784-9590-4d58-87a4-cde0391d95e8","html_url":"https://github.com/keystroke3/census","commit_stats":null,"previous_names":["keystroke3/filesurf"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/keystroke3/census","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keystroke3%2Fcensus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keystroke3%2Fcensus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keystroke3%2Fcensus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keystroke3%2Fcensus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/keystroke3","download_url":"https://codeload.github.com/keystroke3/census/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keystroke3%2Fcensus/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265009232,"owners_count":23697156,"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","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":[],"created_at":"2025-05-16T01:12:21.812Z","updated_at":"2025-07-12T15:11:27.475Z","avatar_url":"https://github.com/keystroke3.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Census\nA small tool for recursively searching your directories for quick and easy fuzzy searching.\n\n\n## Setup\nThe easiest way to install Census is to download the [latest release](https://github.com/keystroke3/Census/releases/latest) binary.\nYou can then place the binary in directory that is in your system PATH, typically `/usr/bin`, `/usr/local/bin` or `~/.local/bin`.\n\n```bash\nwget -O census https://github.com/keystroke3/Census/releases/download/\u003clatest-version\u003ecensus\nchmod +x census\n./census --help\n```\n\nAlternatively, you can download the source code from the archive files in the releases, extract and build from source:\n\n\n```bash\nmkdir census\ncd census\nwget https://github.com/keystroke3/Census/archive/refs/tags/\u003cverion\u003e.tar.gz\ntar -xzvf \u003cversion\u003e.tar.gz\ncd Census-\u003cversion\u003e\ngo build . # add custom flags\n```\n\nIn order for the build to work, you must have Golang and all the Golang tooling installed on your system.\n\n---\n\n**Tip**\n\nYou might want to rename the binary to something shorter like fs or set up a shell alias so you have less typing to do\n\n---\n\n## Usage\n\nFor a quick usage guide, just run:\n```bash\ncensus --help\n```\n\ncensus capabilities:\n - List all the items in the current directory\n - List all the files in multiple given directories\n - Perform REGEX filters on the search results\n - Run as a TCP server\n - Remotely call another census instance over http\n\n### Listing\n\n#### Simple\nThe main thing that census does is list items, so it is pretty easy to do that. If you want to list all the items in the \ncurrent working directory, call census with no arguments. The paths will be listed in full from the root `-p` path\nIf for example we are in the directory `/pics`:\n\n```bash\n$ census\n/pics/cars/ford/blue-mustang.png\n/pics/cars/ford/red-fiesta.png\n/pics/cars/chevrolet/silverado-truck.png\n/pics/cars/chevrolet/camaro.png\n/pics/animals/cats/fluffy-kitten.png\n/pics/animals/cats/sleeping-tabby.png\n/pics/animals/cats/playful-calico.png\n/pics/animals/dogs/german-shepherd-puppy.png\n/pics/animals/dogs/golden-retriever-puppy.png\n/pics/animals/dogs/rottweiler-adult.png\n/pics/animals/dogs/beagle-puppy.png\n/pics/animals/dogs/husky-puppy.png\n/pics/animals/dogs/labrador-retriever-adult.png\n/pics/animals/dogs/poodle-puppy.png\n```\n\nBy default, only the files are shown. If you wish to show directories instead, use the `-d` flag::\n\n```bash\n$ census -p /pics -d\n/pics/cars/ford\n/pics/cars/chevrolet\n/pics/animals/cats\n/pics/animals/dogs\n```\n\n####  Multi-directory listing\n\nIf you want to list items in more directories, you can use the `-p` or `--path` parameter for each directory you wish to add.\nIn the `/pics` example, you can specify\n```bash\n$ census -p /animals/cats  -p /pics/cars/ford\n/pics/cars/ford/blue-mustang.png\n/pics/cars/ford/red-fiesta.png\n/pics/animals/cats/fluffy-kitten.png\n/pics/animals/cats/sleeping-tabby.png\n/pics/animals/cats/playful-calico.png\n```\n\n#### Hidden Items \n\nBy default items starting with a period '`.`' in their name are ignored unless they are explicitly included in the requested paths with `-p` parameter.\nIf you want them to be indexed, you can use the `-H` or `--hidden` flag. Please note that it is more performant to explicitly provide the specific\ndirectory you wish to be included rather than enabling all the hidden directories. Especially if you have a slow drive.\n\nExample:\n\n```bash\n$ census -p .homework\n.homework/totally.png\n.homework/real.png\n.homework/homework.png\n.homework/nothing.png\n.homework/to.png\n.homework/see.png\n.homework/here.png\n\n```\nIn this example, the extra `/pics/.homework/.secret` will not be shown.\n\n### Filtering\n\n#### Grep\nFiltering of the results shown is done using  `-g \u003cregexp\u003e` or `--grep \u003cregexp\u003e` to *keep* items that contain `\u003cregexp\u003e` and `-v` or `--vgrep` to *remove* items\nthat contain `\u003cregexp\u003e`.\n\nFor example:\n\n```bash\n$ census -g 'dogs'\n\n/pics/animals/dogs/german-shepherd-puppy.png\n/pics/animals/dogs/golden-retriever-puppy.png\n/pics/animals/dogs/rottweiler-adult.png\n/pics/animals/dogs/beagle-puppy.png\n/pics/animals/dogs/husky-puppy.png\n/pics/animals/dogs/labrador-retriever-adult.png\n/pics/animals/dogs/poodle-puppy.png\n```\n\nMultiple parameters can be combined in a single command:\n\n```bash\n$ census -g 'dogs' -v 'puppy'\n\n/pics/animals/dogs/labrador-retriever-adult.png\n/pics/animals/dogs/rottweiler-adult.png\n```\nThey can also be can be repeated for extra filtering:\n\n```bash\n$ census -g 'dogs' -v 'puppy' -g 'lab'\n\n/pics/animals/dogs/labrador-retriever-adult.png\n```\n\nThe order in which the parameters are given is the order in which the filtering happens. Just as shown in the examples,\nadding a second `-g` parameter does a new 'grep' operation on the results of the previous parameters. This is what happened in the last example:\n 1. Find all the paths in the current directory\n 2. Isolate the paths that contain 'dogs'\n 3. Remove the ones that contain 'puppy' from the dogs\n 4. return the labradors in the remaining non-puppy dogs\n\n#### Ignore\n\nYou can ignore directories with `-i` or `--ignore` just as you can include them with `-p`. This might look similar to the grep parameters, but it behaves differently.\nWhen a directory is ignored, it will not be visited at all, so it will make the file walking much faster if the directory being ignored is big. Ignoring files doesn't\nhave any impact, so that has not been added as an option.\n\n#### Depth\n\nIf you have a particularly deep directory structure, and what you are looking for is relatively shallow, then it might be a good idea to limit the depth of search.\nJust like ignore, it will stop searching when it reaches a certain depth and therefor save a bunch of time.\n\n### Remoting\n\nSuppose you have a Network Attached Storage (NAS) drive and you want to quickly fuzz out some of its contents. The simplest solution would\nbe to mount the NAS drive somewhere using something like SAMBA or NFS, and then run census on the mount directory. This will work\nbut it will be very slow and inefficient. Also, if you for some reason don't want to or can't mount the directory in question, then this might not\nwork for you. \n\nThis is where the census `--serve` or `-s` parameter comes in handy. When the `--serve` parameter is passed with an addres `addr`, a new TCP listener will be started\nand listen at the specified host and port. You can provide a full address like `127.0.0.1:8080` or just specify the port `:8080` and it will be assumed to be listening on localhost.\nIf the port is being used, then the connection will fail and the listener will not be started.\n\n```bash\n$ census --serve ':8888' \n```\n\nOnce the server is running, you can make requests to it using `--host` parameter. Everything runs just as on local machine, but all the flags and parameters are sent out to the\nremote census instance where they are executed and the results are returned.\n\nYou can run the TCP server in the background like this:\n\n```bash\n$ census --serve ':8888' \u0026\u003e /tmp/census.log \u0026 disown\n```\n\nFor a more convenient way to run it, you can define a systemd service in `/etc/systemd/system/census.service` like so:\n\n```systemd\n[Unit]\nDescription='census TCP server'\n\n[Service]\nUser=\u003cyour_user\u003e\nExecStart=/path/to/census -s '\u003cip\u003e:\u003cport\u003e'\n\n[Install]\nWantedBy=multi-user.target\n```\nDon't for get to restart systemd daemon and enable the newly created census service so it starts at boot:\n\n```bash\n$ sudo systemctl daemon-reload\n$ sudo systemctl enable census\n$ sudo systemctl start census\n```\n\n\n---\n\n**WARNING**\n\n\u003e census will walk the full directories it is instructed to if it has read access. While census does not read the contents of the files, it can be exploited by an attacker while performing\n\u003e reconnaissance to get a lay of the land they are about to attack.\n\u003e You should only use the TCP server behind a firewall in a controlled LAN environment with the port blocked form outside access. Do not expose the listening port to the wider\n\u003e internet unless you are aware of the risks and are willing to take it or have mitigations for it.\n\u003e I have some plans for adding ssh, key-pair and password support, with the last being the first to be implemented, but those are just plans for now.\n\n___\n\n\nIf you wish to send the requests directly using outside tools like curl or use it scripts, you can. Just make sure the commands have the JSON format (capitalization is important):\n\n```go\nstruct {\n\tDepth       int // required (-1 for infinite)\n\tDirMode     bool // false\n\tGrep        string // \"\"\n\tIgnorePaths []string // []\n\tPaths       []string // required\n\tShowHidden  bool // false\n\tVgrep       string // \"\"\n}\n\n```\n\nAny flags or parameters not set or desired can be left out and the default values will be used.\nThe exception is the `Paths` and `Depth` parameters which must be provided when using external tools.  \nhere is an example using curl:\n\n```bash\ncurl telnet://zen:10002 \u003c\u003c\u003c '{\"Depth\":-1,\"DirMode\":false,\"IgnorePaths\":[\"services\"],\"Paths\":[\"/media\"]}'\n```\n`/etc/hosts` entry for `zen` has been mapped to `10.0.0.2` where census server is running.\nThis will also work if you have ssh hostnames defined in `~/.ssh/config`. In my case, the same machine is has the identity `zenith` in ssh config:\n\n```bash\ncurl telnet://zenith:10002 \u003c\u003c\u003c '{\"Depth\":-1,\"DirMode\":false,\"IgnorePaths\":[\"services\"],\"Paths\":[\"/media\"]}'\n```\n\n## Support\nIf you are happy with census and would like to support the project, here are some things you can do:\n\n1. Tell people about the project. This will get more eyes on it and help it grow.\n2. Contribute. I am open to people's contributions, be it bug fixes, new features, translations, etc.\n3. Fill my coffee cup through paypal: paypal@okello.io. This will give me more energy and incentive to keep working on this tool.\n\n\nDISCLAIMER:\ncensus is a hobby project created for personal use and made public for others to use and contribute to. The authors are not responsible for any data loss or damages that may result in \nuse of census.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeystroke3%2Fcensus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkeystroke3%2Fcensus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeystroke3%2Fcensus/lists"}