{"id":13676156,"url":"https://github.com/captainGeech42/synapse-sinkdb","last_synced_at":"2025-04-29T03:30:34.120Z","repository":{"id":103102272,"uuid":"596828474","full_name":"captainGeech42/synapse-sinkdb","owner":"captainGeech42","description":"Synapse Rapid Power-up for SinkDB","archived":false,"fork":false,"pushed_at":"2023-02-04T18:34:40.000Z","size":123,"stargazers_count":10,"open_issues_count":2,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-11-11T17:45:47.019Z","etag":null,"topics":["sinkdb","synapse"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/captainGeech42.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":"2023-02-03T02:19:49.000Z","updated_at":"2023-11-17T00:57:32.000Z","dependencies_parsed_at":"2023-07-25T14:45:26.151Z","dependency_job_id":null,"html_url":"https://github.com/captainGeech42/synapse-sinkdb","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captainGeech42%2Fsynapse-sinkdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captainGeech42%2Fsynapse-sinkdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captainGeech42%2Fsynapse-sinkdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captainGeech42%2Fsynapse-sinkdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/captainGeech42","download_url":"https://codeload.github.com/captainGeech42/synapse-sinkdb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251426701,"owners_count":21587634,"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":["sinkdb","synapse"],"created_at":"2024-08-02T13:00:19.279Z","updated_at":"2025-04-29T03:30:33.832Z","avatar_url":"https://github.com/captainGeech42.png","language":"Python","funding_links":[],"categories":["Power-Ups"],"sub_categories":["Rapid Power-Ups"],"readme":"# synapse-sinkdb\n[![Tests](https://github.com/captainGeech42/synapse-sinkdb/actions/workflows/test.yml/badge.svg)](https://github.com/captainGeech42/synapse-sinkdb/actions/workflows/test.yml) [![Release](https://github.com/captainGeech42/synapse-sinkdb/actions/workflows/release.yml/badge.svg)](https://github.com/captainGeech42/synapse-sinkdb/actions/workflows/release.yml) [![GitHub Release](https://img.shields.io/github/release/captainGeech42/synapse-sinkdb.svg?style=flat)](https://github.com/captainGeech42/synapse-sinkdb/releases)\n\nSynapse Rapid Powerup for [SinkDB](https://sinkdb.abuse.ch/)\n\n## Install\n\nTo install the latest release, run the following Storm command\n\n```\nstorm\u003e pkg.load --raw https://github.com/captainGeech42/synapse-sinkdb/releases/latest/download/synapse_sinkdb.json\n```\n\nYou can also clone this repo, and install via the telepath API:\n\n```\n$ python -m synapse.tools.genpkg --push aha://mycortex synapse-sinkdb.yaml\n```\n\n## Usage\n\nFirst, configure your HTTPS API key (globally, or per user with `--self`):\n\n```\nstorm\u003e zw.sinkdb.setup.apikey \u003capi key here\u003e\n```\n\nOptionally, you can also change the tag prefix (default is `rep.sinkdb`):\n\n```\nstorm\u003e zw.sinkdb.setup.tagprefix 3p.aka.sinkdb\n```\n\nThen, you can lookup IOCs against SinkDB:\n\n```\nstorm\u003e inet:fqdn=ns1.mysinkhole.lol | zw.sinkdb.lookup\n................\ninet:fqdn=ns1.mysinkhole.lol\n        :domain = mysinkhole.lol\n        :host = ns1\n        :issuffix = False\n        :iszone = False\n        :zone = mysinkhole.lol\n        .created = 2023/02/04 02:11:24.673\n        #rep.sinkdb.class.listed = (2023/02/04 02:14:02.284, 2023/02/04 02:14:02.285)\n        #rep.sinkdb.has_operator = (2023/02/04 02:14:02.284, 2023/02/04 02:14:02.285)\n        #rep.sinkdb.sinkhole = (2021/06/27 19:46:08.000, 2023/02/04 02:14:02.284)\n        #rep.sinkdb.type.nameserver = (2023/02/04 02:14:02.284, 2023/02/04 02:14:02.285)\n        #test\ncomplete. 1 nodes in 706 ms (1/sec).\n```\n\nYou can also bulk import the `listed` indicators from SinkDB:\n\n```\nstorm\u003e zw.sinkdb.import\nmodeling 445 records from sinkdb\ncomplete. 0 nodes in 4412 ms (0/sec).\nstorm\u003e zw.sinkdb.import --yield | count\nmodeling 445 records from sinkdb\nCounted 860 nodes.\ncomplete. 0 nodes in 4813 ms (0/sec).\n```\n\nBy default, `lookup` and `import` use a 30 day cache window. To override this, use the `--asof` flag. To ignore the cached data, specify `--asof now`.\n\nFor more details, please run `help zw.sinkdb`.\n\n### Optic\n\nIf you are an Optic user, there are right-click actions registered for `inet:fqdn`, `inet:email`, and `inet:ipv4` nodes:\n\n![optic screenshot of sinkdb enrichment](./optic-actions.png)\n\n## Administration\n\nThis package exposes two permissions:\n\n* `zw.sinkdb.user`: Intended for general analyst use, allows the invocation of `zw.sinkdb.lookup`\n* `zw.sinkdb.admin`: Intended for administrative/automation use, allows the invocation of `zw.sinkdb.import` and changing of global configuration items\n\nThis package uses a `meta:source` node with the GUID `a9fc8fc6af73f0bf2dda26961f50cfe6`. All observed nodes are edged with `seen` to the `meta:source`. The created `ps:contact` nodes to track the operators use the type `zw.sinkdb.operator`.\n\n## Tag Tree\n\nBy default, this package creates a tag tree under `#rep.sinkdb` (you can change the prefix globally with `zw.sinkdb.setup.tagprefix`):\n\n* `#rep.sinkdb.sinkhole`: The node is a sinkhole\n* `#rep.sinkdb.awareness`: The node is a part of a phishing awareness campaign\n* `#rep.sinkdb.scanner`: The node is a scanner\n* `#rep.sinkdb.has_operator`: The operator of the entry is made known\n* `#rep.sinkdb.expose.vendor`: The sinkhole is exposed to vendors\n* `#rep.sinkdb.expose.lea`: The sinkhole is exclusively exposed to law enforcement agencies\n* `#rep.sinkdb.class.listed`: The entry is classified as \"listed\"\n* `#rep.sinkdb.class.query`: The entry is classified as \"query-only\"\n* `#rep.sinkdb.type.*`: The type of entry on SinkDB (`ipv4`, `ipv6`, `ipv4_range`, `ipv6_range`, `whois_email`, `domain_soa`, `nameserver`, `web_ipv4`, `web_ipv6`, `sending_ipv4`, `sending_ipv6`, `web_url`, `web_domain`, `email_from`, `email_from_name`, `email_subject`)\n  * Please note that SinkDB entries with the type `email_from_name` or `email_subject` are modeled as `it:dev:str` nodes, since the `inet:email:message` form doesn't capture them in a standalone manner. These are only modeled when doing `zw.sinkdb.import` for awareness campaigns.\n\nThe time interval on `#rep.sinkdb.sinkhole` reflects the time data exposed by SinkDB (that is, when it was added to SinkDB, through the current time when the entry was observed on SinkDB)\n\nAn additional tag, `#rep.sinkdb.operator`, is applied on `ps:contact` nodes that are created to track the sinkhole operators.\n\n## Running the test suite\n\nYou must have a SinkDB HTTPS API key to run the tests. Please put the key in `$SYNAPSE_SINKDB_APIKEY` when running the tests.\n\nAdditionally, you must provide your own entries on SinkDB to seed the test cortex, since the data is TLP:AMBER and can't be stored in the public test code. Test data should be a JSON blob in the below structure. Please be mindful of the `ipv4_range` entries, each IP in the range will be looked up.\n\n```\n{\n    \"ipv4\": [],\n    \"ipv4_range\": [],\n    \"domain_soa\": [],\n    \"whois_email\": [],\n    \"nameserver\": []\n}\n```\n\nMake sure you add at least the following indicators (the test suite checks for the combination of tags they provide). They *should* be accessible on any account type, ymmv:\n\n```\nhttps://sinkdb.abuse.ch/sinkholes/indicator/1b26d0e462/\nhttps://sinkdb.abuse.ch/sinkholes/indicator/d9b85decab/\nhttps://sinkdb.abuse.ch/sinkholes/indicator/55b492114b/\nhttps://sinkdb.abuse.ch/sinkholes/indicator/d42a88a939/\nhttps://sinkdb.abuse.ch/sinkholes/indicator/e3fdeea6a0/\n```\n\nThis can be stored on disk and provided as a filepath in `$SYNAPSE_SINKDB_DATA_PATH`, or the data can be stored directly in `$SYNAPSE_SINKDB_DATA`. Optionally, if you can verify SinkDB access to me, I'll send you my test blob to make things easier for you.\n\n```\n$ pip install -r requirements.txt\n$ SYNAPSE_SINKDB_APIKEY=asdf SYNAPSE_SINKDB_DATA_PATH=sinkdb_data.json python -m pytest test_synapse_sinkdb.py\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FcaptainGeech42%2Fsynapse-sinkdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FcaptainGeech42%2Fsynapse-sinkdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FcaptainGeech42%2Fsynapse-sinkdb/lists"}