{"id":19034210,"url":"https://github.com/wenzel/oswatcher","last_synced_at":"2025-04-23T17:44:52.591Z","repository":{"id":66187257,"uuid":"57343300","full_name":"Wenzel/oswatcher","owner":"Wenzel","description":"A framework to track the evolution of Operating Systems over time","archived":false,"fork":false,"pushed_at":"2023-10-10T19:48:28.000Z","size":1481,"stargazers_count":58,"open_issues_count":19,"forks_count":7,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-30T02:04:12.475Z","etag":null,"topics":["filesystem","linux","syscall-table","windows"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Wenzel.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}},"created_at":"2016-04-29T00:43:38.000Z","updated_at":"2024-09-03T17:28:00.000Z","dependencies_parsed_at":"2024-01-07T12:55:24.624Z","dependency_job_id":"31151f7b-82cc-4410-a4b3-079612d6a0aa","html_url":"https://github.com/Wenzel/oswatcher","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wenzel%2Foswatcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wenzel%2Foswatcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wenzel%2Foswatcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wenzel%2Foswatcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Wenzel","download_url":"https://codeload.github.com/Wenzel/oswatcher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249348660,"owners_count":21255298,"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":["filesystem","linux","syscall-table","windows"],"created_at":"2024-11-08T21:43:49.703Z","updated_at":"2025-04-17T14:32:27.550Z","avatar_url":"https://github.com/Wenzel.png","language":"Python","readme":"# OSWatcher\n\n![](https://github.com/Wenzel/oswatcher/workflows/Capture%20Filesystem%20in%20git/badge.svg)\n[![Join the chat at https://gitter.im/oswatcher/Lobby](https://badges.gitter.im/trailofbits/algo.svg)](https://gitter.im/oswatcher/Lobby)\n[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)\n[![tokei](https://tokei.rs/b1/github/Wenzel/oswatcher)](https://github.com/Wenzel/oswatcher)\n[![repo size](https://img.shields.io/github/repo-size/Wenzel/oswatcher)](https://github.com/Wenzel/oswatcher)\n\n\u003e Tracking the evolution of operating systems over time\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Requirements](#requirements)\n- [Install](#install)\n- [Usage](#usage)\n- [Troubleshooting](#troubleshooting)\n- [Maintainers](#maintainers)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Overview\n\nOSWatcher is an ambitious project that aims to track the evolution of operating\nsystems by making `diffs` between recognizable characteristics.\n\nThe core of `OSWatcher` is to build a reference database about every OS\nreleases, that is to be populated by an `extractor` in charge of capturing the\nvarious information that can be extracted from an installed operating system, both online\nand offline, in a reproducible way.\n\nOffline:\n\n- filesystem hierarchy\n- setuid binaries\n- executable properties\n- library graph dependencies\n- statistics around `perl/sh/python` scripts\n- syscall tables\n- kernel configuration\n- cronjobs\n- `/etc` configuration\n\nOnline:\n\n- IDLE memory consumption\n- default processes running\n- mapped libraries\n- listening ports and associated services\n- DNS requests sent\n- unix sockets\n- dbus traffic\n- iptables rules\n- loaded drivers\n\n## Requirements\n\n- `python \u003e= 3.7`\n- `virtualenv`\n- [`libguestfs`](http://libguestfs.org/)\n- [`Docker`](https://www.docker.com/) (_optional_)\n\n## Install\n\n1. Clone repo and submodules\n~~~\ngit clone https://github.com/Wenzel/oswatcher.git\ncd oswatcher\ngit submodule update --init\n~~~\n\n2. Install system dependencies\n\nOn `Ubuntu 18.04`\n\n~~~\nsudo apt-get install virtualenv python3-virtualenv libguestfs0 libguestfs-dev python3-guestfs python3-dev pkg-config libvirt-dev\n~~~\n\n3. Create a `Python3` virtualenv\n~~~\nvirtualenv --system-site-packages -p python3 venv\nsource venv/bin/activate\npip install .\n~~~\n\nNote: We have to use `--system-site-packages` because `libguestfs` is not\navailable on `pip`.\n\n## VM setup\n\nOSWatcher works on VMs stored in `libvirt`, either via `qemu:///session`\nor `qemu:///system`.\n\nNote: `qemu:///session` is recommended as it requires less permission\nand should work without further configuration.\n\n## Example Usage: Filesystem capture in Git\n\n### Hooks configuration\n\nOpen `hooks.json` and edit `/path/to/repo` to an empty git repository (outside of `oswatcher`'s git repo).\n\n~~~JSON\n        {\n            \"name\": \"hooks.filesystem.GitFilesystemHook\",\n            \"configuration\":\n            {\n                \"repo\": \"/home/user/test/git_fs\"\n            }\n        }\n~~~\n\nStart the capture tool on a `VM` and specify the hooks configuration to start\ncapturing the VM's filesystem in the previously configured `git` repository.\n\n~~~\n(venv) $ oswatcher [options] \u003cvm_name\u003e hooks.json\n~~~\n\n## Demo\n\nCapturing Windows XP Filesystem in a git repository ([high-quality](https://drive.google.com/open?id=15JF_Pr-kpCLkeHwaX_cfHUq744BZwsNo))\n\n![Capturing winxp\nfilesystem](https://user-images.githubusercontent.com/964610/78451333-923d5b80-7674-11ea-854d-37a53bd7d3ae.gif)\n\n## Advanced Usage\n\n### Neo4j\n\nSome of `OSWatcher`'s plugins are using `neo4j` as a database.\n- `system.OperatingSystemHook`\n- `filesystem.Neo4jFilesystemHook`\n- `security.SecurityHook`\n\nFollow the instructions in the `db` directory to run a `Neo4j` inside a docker\ncontainer.\n\nModify your `hooks.json` to include a `neo4j` dictionary in the general `configuration` section.\n\nYou will also need to include the:\n- `OperatingSystemHook` at least.\n\nThe rest is optional. \n\nTo visualize the filesystem in `Neo4j`, include the `FilesystemHook` and the `Neo4jFilesystemHook`, like the example below:\n~~~JSON\n{\n    \"configuration\":\n    {\n        \"neo4j\": {\n            \"enabled\": true,\n            \"delete\": false,\n            \"replace\": false\n        },\n        \"desktop_ready_delay\": 90\n    },\n    \"hooks\":\n    [\n        {\n            \"name\": \"hooks.filesystem.LibguestfsHook\"\n        },\n        {\n            \"name\": \"hooks.filesystem.FilesystemHook\",\n            \"configuration\":\n            {\n                \"enumerate\": true,\n                \"log_progress\": true,\n                \"log_progress_delay\": 10\n            }\n        },\n        {\n            \"name\": \"hooks.filesystem.Neo4jFilesystemHook\"\n        }\n    ]\n}\n\n~~~\n\nAccess `Neo4j` web interface at `http://localhost:7474` ![ubuntu etc\nneo4j](https://user-images.githubusercontent.com/964610/47535864-18714200-d8c6-11e8-885b-27d17c8d6235.png)\n\n## Troubleshooting\n\n### libguestfs\n\nIf `libguestfs` fails to initialize, you can use the `libguestfs-test-tool` to\nquickly understand the root cause of the failure.\n\n## Maintainers\n\n[@Wenzel](https://github.com/Wenzel)\n\n## Contributing\n\nPRs accepted.\n\nSmall note: If editing the Readme, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification.\n\n## License\n\n[GNU General Public License v3.0](https://github.com/Wenzel/oswatcher/blob/master/LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwenzel%2Foswatcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwenzel%2Foswatcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwenzel%2Foswatcher/lists"}