<a href="https://gitguardian.com/"><img src="https://cdn.jsdelivr.net/gh/gitguardian/py-gitguardian/doc/logo.svg"></a>
# [py-gitguardian](https://github.com/GitGuardian/py-gitguardian) - GitGuardian API Client
[](https://pypi.org/project/pygitguardian/)
[](LICENSE)
[](https://github.com/GitGuardian/py-gitguardian/stargazers)
[](https://codecov.io/gh/GitGuardian/py-gitguardian/)
API client library for the [GitGuardian API](https://api.gitguardian.com/).
The GitGuardian API puts at your fingertips the power to detect more than 200 types of secrets in any text content, as well as other potential security vulnerabilities.
**py-gitguardian** can be used to create integrations to scan various data sources, from your workstation's filesystem to your favorite chat application.
You can check API details [here](https://api.gitguardian.com/docs)
with all the response codes and expected structures on each method.
## Requirements
Python 3.8+
## Projects using `py-gitguardian`
- [**GitGuardian Shield**](https://github.com/GitGuardian/gg-shield) - Scan for secrets in your CI and pre-commit.
## Getting started
You can obtain API keys for API usage on your [dashboard](https://dashboard.gitguardian.com/api/v1/auth/user/github_login/authorize?utm_source=github&utm_medium=py_gitguardian&utm_campaign=py1).
**pip**
```bash
pip3 install --upgrade pygitguardian
```
**pipenv**
```bash
pipenv install pygitguardian
```
**pdm**
```bash
pdm add pygitguardian
```
**poetry**
```bash
poetry add pygitguardian
```
## Examples
Check [examples/](examples/) for full examples on how to use py-gitguardian.
### Scanning text content
```py
# please don't hardcode your gg_api_key in source code :)
API_KEY = os.getenv("GITGUARDIAN_API_KEY")
DOCUMENT = """
import urllib.request
url = 'http://jen_barber:correcthorsebatterystaple@cake.gitguardian.com/isreal.json'
response = urllib.request.urlopen(url)
consume(response.read())"
"""
client = GGClient(api_key=API_KEY)
# Check the health of the API and the API key used.
if client.health_check().success:
try:
scan_result = client.content_scan(DOCUMENT)
except Exception as exc:
# Handle exceptions such as schema validation
traceback.print_exc(2, file=sys.stderr)
print(str(exc))
print(scan_result)
else:
print("Invalid API Key")
```
### Scanning multiple files
```py
API_KEY = os.getenv("GITGUARDIAN_API_KEY")
client = GGClient(api_key=API_KEY)
# Create a list of dictionaries for scanning
file_paths = (pathlib.Path(name) for name in glob.iglob("**/*", recursive=True))
to_scan = [
{"filename": path.name, "document": path.read_text(errors="replace")}
for path in file_paths
]
scan = client.multi_content_scan(to_scan)
```
### Transform results to dict or JSON
Any model in `py-gitguardian` can be turned to a JSON string or a dictionary using
the `to_dict` and `to_json` methods.
```py
from pygitguardian.models import Detail
detail = Detail("Invalid API Key.")
print(detail.to_dict())
print(detail.to_json())
```
### Dependencies
Py-gitguardian depends on these excellent libraries:
- `requests` - HTTP client
- `marshmallow` - Request (de)serialization and input validation
Raw data
{
"_id": null,
"home_page": null,
"name": "pygitguardian",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "GitGuardian <support@gitguardian.com>",
"keywords": "api-client devsecops secrets-detection security-tools library gitguardian",
"author": null,
"author_email": "GitGuardian <support@gitguardian.com>",
"download_url": "https://files.pythonhosted.org/packages/25/b8/599e73a3e2ee7466f70ddb39b7ccce04aa3a4b59140755378dd2a01031e2/pygitguardian-1.17.0.tar.gz",
"platform": null,
"description": "<a href=\"https://gitguardian.com/\"><img src=\"https://cdn.jsdelivr.net/gh/gitguardian/py-gitguardian/doc/logo.svg\"></a>\n\n# [py-gitguardian](https://github.com/GitGuardian/py-gitguardian) - GitGuardian API Client\n\n[](https://pypi.org/project/pygitguardian/)\n[](LICENSE)\n[](https://github.com/GitGuardian/py-gitguardian/stargazers)\n\n[](https://codecov.io/gh/GitGuardian/py-gitguardian/)\n\nAPI client library for the [GitGuardian API](https://api.gitguardian.com/).\n\nThe GitGuardian API puts at your fingertips the power to detect more than 200 types of secrets in any text content, as well as other potential security vulnerabilities.\n\n**py-gitguardian** can be used to create integrations to scan various data sources, from your workstation's filesystem to your favorite chat application.\n\nYou can check API details [here](https://api.gitguardian.com/docs)\nwith all the response codes and expected structures on each method.\n\n## Requirements\n\nPython 3.8+\n\n## Projects using `py-gitguardian`\n\n- [**GitGuardian Shield**](https://github.com/GitGuardian/gg-shield) - Scan for secrets in your CI and pre-commit.\n\n## Getting started\n\nYou can obtain API keys for API usage on your [dashboard](https://dashboard.gitguardian.com/api/v1/auth/user/github_login/authorize?utm_source=github&utm_medium=py_gitguardian&utm_campaign=py1).\n\n**pip**\n\n```bash\npip3 install --upgrade pygitguardian\n```\n\n**pipenv**\n\n```bash\npipenv install pygitguardian\n```\n\n**pdm**\n\n```bash\npdm add pygitguardian\n```\n\n**poetry**\n\n```bash\npoetry add pygitguardian\n```\n\n## Examples\n\nCheck [examples/](examples/) for full examples on how to use py-gitguardian.\n\n### Scanning text content\n\n```py\n# please don't hardcode your gg_api_key in source code :)\nAPI_KEY = os.getenv(\"GITGUARDIAN_API_KEY\")\nDOCUMENT = \"\"\"\n import urllib.request\n url = 'http://jen_barber:correcthorsebatterystaple@cake.gitguardian.com/isreal.json'\n response = urllib.request.urlopen(url)\n consume(response.read())\"\n\"\"\"\n\nclient = GGClient(api_key=API_KEY)\n\n# Check the health of the API and the API key used.\nif client.health_check().success:\n try:\n scan_result = client.content_scan(DOCUMENT)\n except Exception as exc:\n # Handle exceptions such as schema validation\n traceback.print_exc(2, file=sys.stderr)\n print(str(exc))\n print(scan_result)\nelse:\n print(\"Invalid API Key\")\n```\n\n### Scanning multiple files\n\n```py\nAPI_KEY = os.getenv(\"GITGUARDIAN_API_KEY\")\nclient = GGClient(api_key=API_KEY)\n\n# Create a list of dictionaries for scanning\nfile_paths = (pathlib.Path(name) for name in glob.iglob(\"**/*\", recursive=True))\nto_scan = [\n {\"filename\": path.name, \"document\": path.read_text(errors=\"replace\")}\n for path in file_paths\n]\n\nscan = client.multi_content_scan(to_scan)\n```\n\n### Transform results to dict or JSON\n\nAny model in `py-gitguardian` can be turned to a JSON string or a dictionary using\nthe `to_dict` and `to_json` methods.\n\n```py\nfrom pygitguardian.models import Detail\n\ndetail = Detail(\"Invalid API Key.\")\nprint(detail.to_dict())\nprint(detail.to_json())\n```\n\n### Dependencies\n\nPy-gitguardian depends on these excellent libraries:\n\n- `requests` - HTTP client\n- `marshmallow` - Request (de)serialization and input validation\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python Wrapper for GitGuardian's API -- Scan security policy breaks everywhere",
"version": "1.17.0",
"project_urls": {
"Homepage": "https://github.com/GitGuardian/py-gitguardian"
},
"split_keywords": [
"api-client",
"devsecops",
"secrets-detection",
"security-tools",
"library",
"gitguardian"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "51b02b439a6ebeb37b2c3a834e0ec8f2d3917b060eb223fecf71dc42125df494",
"md5": "9c29535a211eadeb8da76fee95d959bc",
"sha256": "ddfe97312d21133fd50848a532560397b5342587420c5207701efa83c630b3a2"
},
"downloads": -1,
"filename": "pygitguardian-1.17.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9c29535a211eadeb8da76fee95d959bc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 20032,
"upload_time": "2024-09-23T10:06:38",
"upload_time_iso_8601": "2024-09-23T10:06:38.768726Z",
"url": "https://files.pythonhosted.org/packages/51/b0/2b439a6ebeb37b2c3a834e0ec8f2d3917b060eb223fecf71dc42125df494/pygitguardian-1.17.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "25b8599e73a3e2ee7466f70ddb39b7ccce04aa3a4b59140755378dd2a01031e2",
"md5": "a8ed128a9d9de948b5f8c7b11739ed84",
"sha256": "17ef91e7fe954f7b8d91f39c0097ba49b07e77b5ee9d0596adad256a9d4ab71e"
},
"downloads": -1,
"filename": "pygitguardian-1.17.0.tar.gz",
"has_sig": false,
"md5_digest": "a8ed128a9d9de948b5f8c7b11739ed84",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 44598,
"upload_time": "2024-09-23T10:06:39",
"upload_time_iso_8601": "2024-09-23T10:06:39.863731Z",
"url": "https://files.pythonhosted.org/packages/25/b8/599e73a3e2ee7466f70ddb39b7ccce04aa3a4b59140755378dd2a01031e2/pygitguardian-1.17.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-23 10:06:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GitGuardian",
"github_project": "py-gitguardian",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pygitguardian"
}
JSON
