<a href="https://pangea.cloud?utm_source=github&utm_medium=python-sdk" target="_blank" rel="noopener noreferrer">
<img src="https://pangea-marketing.s3.us-west-2.amazonaws.com/pangea-color.svg" alt="Pangea Logo" height="40" />
</a>
<br />
[][Documentation]
[][Slack]
# Pangea Python SDK
A Python SDK for integrating with Pangea services. Supports Python v3.7 and
above.
## Installation
Via pip:
```bash
$ pip3 install pangea-sdk
```
Via poetry:
```bash
$ poetry add pangea-sdk
```
<a name="beta-releases"></a>
### Beta releases
Pre-release versions may be available with the `b` (beta) denotation in the
version number. These releases serve to preview beta services and APIs. Per
Semantic Versioning, they are considered unstable and do not carry the same
compatibility guarantees as stable releases. [Beta changelog](https://github.com/pangeacyber/pangea-python/blob/beta/CHANGELOG.md).
Via pip:
```bash
$ pip3 install pangea-sdk==3.8.0b1
```
Via poetry:
```bash
$ poetry add pangea-sdk==3.8.0b1
```
## Usage
- [Documentation][]
- [Examples][]
General usage would be to create a token for a service through the
[Pangea Console][] and then construct an API client for that respective service.
The below example shows how this can be done for [Secure Audit Log][] to log a
simple event:
```python
import os
from pangea.config import PangeaConfig
from pangea.services import Audit
# Load client configuration from environment variables `PANGEA_AUDIT_TOKEN` and
# `PANGEA_DOMAIN`.
token = os.getenv("PANGEA_AUDIT_TOKEN")
domain = os.getenv("PANGEA_DOMAIN")
config = PangeaConfig(domain=domain)
# Create a Secure Audit Log client.
audit = Audit(token, config)
# Log a basic event.
response = audit.log(message="Hello, World!")
```
## asyncio support
asyncio support is available through the `pangea.asyncio.services` module. The
previous example may be rewritten to utilize async/await syntax like so:
```python
import asyncio
import os
from pangea.asyncio.services import AuditAsync
from pangea.config import PangeaConfig
# Load client configuration from environment variables `PANGEA_AUDIT_TOKEN` and
# `PANGEA_DOMAIN`.
token = os.getenv("PANGEA_AUDIT_TOKEN")
domain = os.getenv("PANGEA_DOMAIN")
config = PangeaConfig(domain=domain)
# Create a Secure Audit Log client.
audit = AuditAsync(token, config=config)
async def main():
# Log a basic event.
response = await audit.log(message="Hello, World!")
await audit.close()
if __name__ == "__main__":
asyncio.run(main())
```
## Secure Audit Log - Integrity Tools
The Python Pangea SDK also includes some extra features to validate Audit Service log's integrity. Here we explain how to run them.
### Verify audit data
Verify that an event or a list of events has not been tampered with. Usage:
```
usage: python -m pangea.verify_audit [-h] [--file PATH]
or
usage: poetry run python -m pangea.verify_audit [-h] [--file PATH]
Pangea Audit Verifier
options:
-h, --help show this help message and exit
--file PATH, -f PATH Input file (default: standard input).
```
It accepts multiple file formats:
- a Verification Artifact from the Pangea User Console
- a search response from the REST API:
```bash
$ curl -H "Authorization: Bearer ${PANGEA_TOKEN}" -X POST -H 'Content-Type: application/json' --data '{"verbose": true}' https://audit.aws.us.pangea.cloud/v1/search
```
### Bulk Download Audit Data
Download all audit logs for a given time range. Start and end date should be provided,
a variety of formats is supported, including ISO-8601. The result is stored in a
json file (one json per line).
```
usage: python -m pangea.dump_audit [-h] [--token TOKEN] [--domain DOMAIN] [--output OUTPUT] start end
or
usage: poetry run python -m pangea.dump_audit [-h] [--token TOKEN] [--domain DOMAIN] [--output OUTPUT] start end
Pangea Audit Dump Tool
positional arguments:
start Start timestamp. Supports a variety of formats, including ISO-8601. e.g.: 2023-06-05T18:05:15.030667Z
end End timestamp. Supports a variety of formats, including ISO-8601. e.g.: 2023-06-05T18:05:15.030667Z
options:
-h, --help show this help message and exit
--token TOKEN, -t TOKEN
Pangea token (default: env PANGEA_TOKEN)
--domain DOMAIN, -d DOMAIN
Pangea base domain (default: env PANGEA_DOMAIN)
--output OUTPUT, -o OUTPUT
Output file name. Default: dump-<timestamp>
```
### Perform Exhaustive Verification of Audit Data
This script performs extensive verification on a range of events of the log stream. Apart from verifying the hash
and the membership proof, it checks that there are no omissions in the stream, i.e. all the events are present and properly located.
```
usage: python -m pangea.deep_verify [-h] [--token TOKEN] [--domain DOMAIN] --file FILE
or
usage: poetry run python -m pangea.deep_verify [-h] [--token TOKEN] [--domain DOMAIN] --file FILE
Pangea Audit Event Deep Verifier
options:
-h, --help show this help message and exit
--token TOKEN, -t TOKEN
Pangea token (default: env PANGEA_TOKEN)
--domain DOMAIN, -d DOMAIN
Pangea base domain (default: env PANGEA_DOMAIN)
--file FILE, -f FILE Event input file. Must be a collection of JSON Objects separated by newlines
```
It accepts multiple file formats:
- a Verification Artifact from the Pangea User Console
- a file generated by the `dump_audit` command
- a search response from the REST API (see `verify_audit`)
[Documentation]: https://pangea.cloud/docs/sdk/python/
[Examples]: https://github.com/pangeacyber/pangea-python/tree/main/examples
[Pangea Console]: https://console.pangea.cloud/
[Slack]: https://pangea.cloud/join-slack/
[Secure Audit Log]: https://pangea.cloud/docs/audit
Raw data
{
"_id": null,
"home_page": "https://pangea.cloud/docs/sdk/python/",
"name": "pangea-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.7.2",
"maintainer_email": null,
"keywords": "Pangea, SDK, Audit",
"author": "Glenn Gallien",
"author_email": "glenn.gallien@pangea.cloud",
"download_url": "https://files.pythonhosted.org/packages/41/9c/4d96c09a6120a3bea34a0eab2fbd361afc9f5c8a833735758bfbee455984/pangea_sdk-3.7.1.tar.gz",
"platform": null,
"description": "<a href=\"https://pangea.cloud?utm_source=github&utm_medium=python-sdk\" target=\"_blank\" rel=\"noopener noreferrer\">\n <img src=\"https://pangea-marketing.s3.us-west-2.amazonaws.com/pangea-color.svg\" alt=\"Pangea Logo\" height=\"40\" />\n</a>\n\n<br />\n\n[][Documentation]\n[][Slack]\n\n# Pangea Python SDK\n\nA Python SDK for integrating with Pangea services. Supports Python v3.7 and\nabove.\n\n## Installation\n\nVia pip:\n\n```bash\n$ pip3 install pangea-sdk\n```\n\nVia poetry:\n\n```bash\n$ poetry add pangea-sdk\n```\n\n<a name=\"beta-releases\"></a>\n\n### Beta releases\n\nPre-release versions may be available with the `b` (beta) denotation in the\nversion number. These releases serve to preview beta services and APIs. Per\nSemantic Versioning, they are considered unstable and do not carry the same\ncompatibility guarantees as stable releases. [Beta changelog](https://github.com/pangeacyber/pangea-python/blob/beta/CHANGELOG.md).\n\nVia pip:\n\n```bash\n$ pip3 install pangea-sdk==3.8.0b1\n```\n\nVia poetry:\n\n```bash\n$ poetry add pangea-sdk==3.8.0b1\n```\n\n## Usage\n\n- [Documentation][]\n- [Examples][]\n\nGeneral usage would be to create a token for a service through the\n[Pangea Console][] and then construct an API client for that respective service.\nThe below example shows how this can be done for [Secure Audit Log][] to log a\nsimple event:\n\n```python\nimport os\n\nfrom pangea.config import PangeaConfig\nfrom pangea.services import Audit\n\n# Load client configuration from environment variables `PANGEA_AUDIT_TOKEN` and\n# `PANGEA_DOMAIN`.\ntoken = os.getenv(\"PANGEA_AUDIT_TOKEN\")\ndomain = os.getenv(\"PANGEA_DOMAIN\")\nconfig = PangeaConfig(domain=domain)\n\n# Create a Secure Audit Log client.\naudit = Audit(token, config)\n\n# Log a basic event.\nresponse = audit.log(message=\"Hello, World!\")\n```\n\n## asyncio support\n\nasyncio support is available through the `pangea.asyncio.services` module. The\nprevious example may be rewritten to utilize async/await syntax like so:\n\n```python\nimport asyncio\nimport os\n\nfrom pangea.asyncio.services import AuditAsync\nfrom pangea.config import PangeaConfig\n\n# Load client configuration from environment variables `PANGEA_AUDIT_TOKEN` and\n# `PANGEA_DOMAIN`.\ntoken = os.getenv(\"PANGEA_AUDIT_TOKEN\")\ndomain = os.getenv(\"PANGEA_DOMAIN\")\nconfig = PangeaConfig(domain=domain)\n\n# Create a Secure Audit Log client.\naudit = AuditAsync(token, config=config)\n\n\nasync def main():\n # Log a basic event.\n response = await audit.log(message=\"Hello, World!\")\n\n await audit.close()\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n## Secure Audit Log - Integrity Tools\n\nThe Python Pangea SDK also includes some extra features to validate Audit Service log's integrity. Here we explain how to run them.\n\n### Verify audit data\n\nVerify that an event or a list of events has not been tampered with. Usage:\n\n```\nusage: python -m pangea.verify_audit [-h] [--file PATH]\nor\nusage: poetry run python -m pangea.verify_audit [-h] [--file PATH]\n\nPangea Audit Verifier\n\noptions:\n -h, --help show this help message and exit\n --file PATH, -f PATH Input file (default: standard input).\n```\n\nIt accepts multiple file formats:\n- a Verification Artifact from the Pangea User Console\n- a search response from the REST API:\n\n```bash\n$ curl -H \"Authorization: Bearer ${PANGEA_TOKEN}\" -X POST -H 'Content-Type: application/json' --data '{\"verbose\": true}' https://audit.aws.us.pangea.cloud/v1/search\n```\n\n\n### Bulk Download Audit Data\n\nDownload all audit logs for a given time range. Start and end date should be provided,\na variety of formats is supported, including ISO-8601. The result is stored in a\njson file (one json per line).\n\n```\nusage: python -m pangea.dump_audit [-h] [--token TOKEN] [--domain DOMAIN] [--output OUTPUT] start end\nor\nusage: poetry run python -m pangea.dump_audit [-h] [--token TOKEN] [--domain DOMAIN] [--output OUTPUT] start end\n\nPangea Audit Dump Tool\n\npositional arguments:\n start Start timestamp. Supports a variety of formats, including ISO-8601. e.g.: 2023-06-05T18:05:15.030667Z\n end End timestamp. Supports a variety of formats, including ISO-8601. e.g.: 2023-06-05T18:05:15.030667Z\n\noptions:\n -h, --help show this help message and exit\n --token TOKEN, -t TOKEN\n Pangea token (default: env PANGEA_TOKEN)\n --domain DOMAIN, -d DOMAIN\n Pangea base domain (default: env PANGEA_DOMAIN)\n --output OUTPUT, -o OUTPUT\n Output file name. Default: dump-<timestamp>\n```\n\n### Perform Exhaustive Verification of Audit Data\n\nThis script performs extensive verification on a range of events of the log stream. Apart from verifying the hash\nand the membership proof, it checks that there are no omissions in the stream, i.e. all the events are present and properly located.\n\n```\nusage: python -m pangea.deep_verify [-h] [--token TOKEN] [--domain DOMAIN] --file FILE\nor\nusage: poetry run python -m pangea.deep_verify [-h] [--token TOKEN] [--domain DOMAIN] --file FILE\n\nPangea Audit Event Deep Verifier\n\noptions:\n -h, --help show this help message and exit\n --token TOKEN, -t TOKEN\n Pangea token (default: env PANGEA_TOKEN)\n --domain DOMAIN, -d DOMAIN\n Pangea base domain (default: env PANGEA_DOMAIN)\n --file FILE, -f FILE Event input file. Must be a collection of JSON Objects separated by newlines\n```\n\nIt accepts multiple file formats:\n- a Verification Artifact from the Pangea User Console\n- a file generated by the `dump_audit` command\n- a search response from the REST API (see `verify_audit`)\n\n\n\n [Documentation]: https://pangea.cloud/docs/sdk/python/\n [Examples]: https://github.com/pangeacyber/pangea-python/tree/main/examples\n [Pangea Console]: https://console.pangea.cloud/\n [Slack]: https://pangea.cloud/join-slack/\n [Secure Audit Log]: https://pangea.cloud/docs/audit\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Pangea API SDK",
"version": "3.7.1",
"project_urls": {
"Homepage": "https://pangea.cloud/docs/sdk/python/",
"Repository": "https://github.com/pangeacyber/pangea-python/tree/main/packages/pangea-sdk"
},
"split_keywords": [
"pangea",
" sdk",
" audit"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d8efaae1b49d7d646d7522b071a14a4849fe702b54df64f57031a7da1554d4ab",
"md5": "435f342b6a0768b87888d1a1d00bc8ed",
"sha256": "4726e8e13ca9ecff3fffeb67a77bc38216dc792a8c41c00155bc6cfab9d7919a"
},
"downloads": -1,
"filename": "pangea_sdk-3.7.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "435f342b6a0768b87888d1a1d00bc8ed",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.7.2",
"size": 104598,
"upload_time": "2024-03-20T19:03:57",
"upload_time_iso_8601": "2024-03-20T19:03:57.919493Z",
"url": "https://files.pythonhosted.org/packages/d8/ef/aae1b49d7d646d7522b071a14a4849fe702b54df64f57031a7da1554d4ab/pangea_sdk-3.7.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "419c4d96c09a6120a3bea34a0eab2fbd361afc9f5c8a833735758bfbee455984",
"md5": "f46170ccf62ee3e8483271f929f643c7",
"sha256": "f4da9e12a836d53b28b2512c16828d117bdc1fd8f7b362e4d2105040585e253c"
},
"downloads": -1,
"filename": "pangea_sdk-3.7.1.tar.gz",
"has_sig": false,
"md5_digest": "f46170ccf62ee3e8483271f929f643c7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.7.2",
"size": 87290,
"upload_time": "2024-03-20T19:03:59",
"upload_time_iso_8601": "2024-03-20T19:03:59.474499Z",
"url": "https://files.pythonhosted.org/packages/41/9c/4d96c09a6120a3bea34a0eab2fbd361afc9f5c8a833735758bfbee455984/pangea_sdk-3.7.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-20 19:03:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pangeacyber",
"github_project": "pangea-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pangea-sdk"
}
JSON
