{"id":31956049,"url":"https://github.com/cisagov/cyhy-kevsync","last_synced_at":"2025-10-14T14:47:33.228Z","repository":{"id":255050883,"uuid":"848392191","full_name":"cisagov/cyhy-kevsync","owner":"cisagov","description":"Cyber Hygiene known exploited vulnerability (KEV) synchronization Python library","archived":false,"fork":false,"pushed_at":"2025-07-31T20:29:36.000Z","size":930,"stargazers_count":5,"open_issues_count":2,"forks_count":3,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2025-07-31T21:54:34.933Z","etag":null,"topics":["cyhy","exploited","kev","vulnerabilities","vulnerability"],"latest_commit_sha":null,"homepage":"https://www.cisa.gov/known-exploited-vulnerabilities-catalog","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cisagov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-08-27T17:15:28.000Z","updated_at":"2025-07-31T20:24:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"3387c02a-1fa6-4e38-809f-13de96222dfe","html_url":"https://github.com/cisagov/cyhy-kevsync","commit_stats":null,"previous_names":["cisagov/cyhy-kevsync"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/cisagov/cyhy-kevsync","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisagov%2Fcyhy-kevsync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisagov%2Fcyhy-kevsync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisagov%2Fcyhy-kevsync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisagov%2Fcyhy-kevsync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cisagov","download_url":"https://codeload.github.com/cisagov/cyhy-kevsync/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisagov%2Fcyhy-kevsync/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279019159,"owners_count":26086685,"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","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["cyhy","exploited","kev","vulnerabilities","vulnerability"],"created_at":"2025-10-14T14:47:25.007Z","updated_at":"2025-10-14T14:47:33.216Z","avatar_url":"https://github.com/cisagov.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cyhy-kevsync #\n\n[![GitHub Build Status](https://github.com/cisagov/cyhy-kevsync/workflows/build/badge.svg)](https://github.com/cisagov/cyhy-kevsync/actions)\n[![CodeQL](https://github.com/cisagov/cyhy-kevsync/workflows/CodeQL/badge.svg)](https://github.com/cisagov/cyhy-kevsync/actions/workflows/codeql-analysis.yml)\n[![Coverage Status](https://coveralls.io/repos/github/cisagov/cyhy-kevsync/badge.svg?branch=develop)](https://coveralls.io/github/cisagov/cyhy-kevsync?branch=develop)\n[![Known Vulnerabilities](https://snyk.io/test/github/cisagov/cyhy-kevsync/develop/badge.svg)](https://snyk.io/test/github/cisagov/cyhy-kevsync)\n\n`cyhy-kevsync` is Python library that can retrieve a JSON file containing Known\nExploited Vulnerabilities (such as the [JSON\nfile](https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities_schema.json)\nfor the [CISA Known Exploited Vulnerabilities\nCatalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)) and\nimport the data into a MongoDB collection.\n\n## Pre-requisites ##\n\n- [Python 3.12](https://www.python.org/downloads/) or newer\n- A running [MongoDB](https://www.mongodb.com/) instance that you have access to\n\n## Starting a Local MongoDB Instance for Testing ##\n\n\u003e [!IMPORTANT]\n\u003e This requires [Docker](https://www.docker.com/) to be installed in\n\u003e order for this to work.\n\nYou can start a local MongoDB instance in a container with the following\ncommand:\n\n```console\npytest -vs --mongo-express\n```\n\n\u003e [!NOTE]\n\u003e The command `pytest -vs --mongo-express` not only starts a local\n\u003e MongoDB instance, but also runs all the `cyhy-kevsync` unit tests, which will\n\u003e create various collections and documents in the database.\n\nSample output (trimmed to highlight the important parts):\n\n```console\n\u003csnip\u003e\nMongoDB is accessible at mongodb://mongoadmin:secret@localhost:32784 with database named \"test\"\nMongo Express is accessible at http://admin:pass@localhost:8081\n\nPress Enter to stop Mongo Express and MongoDB containers...\n```\n\nBased on the example output above, you can access the MongoDB instance at\n`mongodb://mongoadmin:secret@localhost:32784` and the Mongo Express web\ninterface at `http://admin:pass@localhost:8081`.  Note that the MongoDB\ncontainers will remain running until you press \"Enter\" in that terminal.\n\n## Example Usage ##\n\nOnce you have a MongoDB instance running, the sample Python code below\ndemonstrates how to initialize the CyHy database, fetch KEV data from a source,\nvalidate it, and then load the data into to your database.\n\n```python\nimport asyncio\nfrom cyhy_db import initialize_db\nfrom cyhy_db.models import KEVDoc\nfrom cyhy_kevsync import DEFAULT_KEV_SCHEMA_URL, DEFAULT_KEV_URL\nfrom cyhy_kevsync.kev_sync import fetch_kev_data, sync_kev_docs, validate_kev_data\n\nasync def main():\n    # Initialize the CyHy database\n    await initialize_db(\"mongodb://mongoadmin:secret@localhost:32784\", \"test\")\n\n    # Count number of KEV documents in DB before sync\n    kev_count_before = await KEVDoc.find_all().count()\n    print(f\"KEV documents in DB before sync: {kev_count_before}\")\n\n    # Fetch KEV data from the default source\n    kev_data = await fetch_kev_data(DEFAULT_KEV_URL)\n\n    # Validate the KEV data against the default schema\n    await validate_kev_data(kev_data, DEFAULT_KEV_SCHEMA_URL)\n\n    # Sync the KEV data to the database\n    await sync_kev_docs(kev_data)\n\n    # Count number of KEV documents in DB after sync\n    kev_count_after = await KEVDoc.find_all().count()\n    print(f\"KEV documents in DB after sync: {kev_count_after}\")\n\nasyncio.run(main())\n```\n\nOutput:\n\n```console\nKEV documents in DB before sync: 0\nProcessing KEV feed ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:01\nDeleting KEV docs ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\nKEV documents in DB after sync: 1193\n```\n\n### Environment Variables ###\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `MONGO_INITDB_ROOT_USERNAME` | The MongoDB root username | `mongoadmin` |\n| `MONGO_INITDB_ROOT_PASSWORD` | The MongoDB root password | `secret` |\n| `DATABASE_NAME` | The name of the database to use for testing | `test` |\n| `MONGO_EXPRESS_PORT` | The port to use for the Mongo Express web interface | `8081` |\n\n### Pytest Options ###\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--mongo-express` | Start a local MongoDB instance and Mongo Express web interface | n/a |\n| `--mongo-image-tag` | The tag of the MongoDB Docker image to use | `docker.io/mongo:latest` |\n| `--runslow` | Run slow tests | n/a |\n\n## Contributing ##\n\nWe welcome contributions!  Please see [`CONTRIBUTING.md`](CONTRIBUTING.md) for\ndetails.\n\n## License ##\n\nThis project is in the worldwide [public domain](LICENSE).\n\nThis project is in the public domain within the United States, and\ncopyright and related rights in the work worldwide are waived through\nthe [CC0 1.0 Universal public domain\ndedication](https://creativecommons.org/publicdomain/zero/1.0/).\n\nAll contributions to this project will be released under the CC0\ndedication. By submitting a pull request, you are agreeing to comply\nwith this waiver of copyright interest.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcisagov%2Fcyhy-kevsync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcisagov%2Fcyhy-kevsync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcisagov%2Fcyhy-kevsync/lists"}