==================================================
PSEngine
==================================================
**PSEngine** is a simple, yet elegant, library for rapid development of integrations with Recorded Future.
.. code-block:: python
>>> from psengine.enrich import LookupMgr
>>> lookup_mgr = LookupMgr(rf_token='token')
>>> domain = lookup_mgr.lookup('cpejcogzznpudbsmaxxm.com', 'domain')
>>> domain
'EnrichedDomain: cpejcogzznpudbsmaxxm.com, Risk Score: 20, Last Seen: 2024-07-22 02:50:59PM'
>>> domain.entity
'cpejcogzznpudbsmaxxm.com'
>>> domain.content.risk
EntityRisk(criticality_label='Unusual', risk_string='4/52', score=20, rules=4...)
>>> domain.content.risk.score
20
>>>
domain.content.risk.risk_summary
'4 of 52 Risk Rules currently observed.'
PSEngine allows you to interact with the Recorded Future API extremely easily. There’s no need to manually build the URLs and query parameters - but nowadays, just use the modules dedicated to individual API endpoints!
PSEngine is a Python package solely built and maintained by the Cyber Security Engineering team powering a number of high profile integrations, such as: Elasticsearch, QRadar, Anomali, Jira, TheHive, etc..
Installation
==================================================
PSEngine is a Python package that can be installed using pip. To install PSengine, run the following command:
.. code-block:: bash
$ pip install psengine
PSEngine officially supports Python >= 3.9, < 3.14
Supported Features & Best–Practices
==================================================
PSEngine is ready for the demands of building robust and reliable integrations.
* Collective Insights
* Analyst Notes
* Classic & Playbook Alerts
* Risklists
* On demand IOC enrichment
* List management
* Detection Rules
* Built in logging
* Easy configuration management
* Proxy support
Quick Start
==================================================
Excited, to get started?
The section below will give you the basic building blocks to start building integrations with PSEngine.
But first ensure that:
- PSEngine is installed
- PSEngine is up-to-date
Let’s get started with some core concepts and practices.
Config Management
--------------------------------------------------
The key requirement when building integrations with PSEngine is initializing `Config` as early as possible in your program,
before initializing any PSEngine managers. This way `rf_token` `app_id` and `platform_id` you set will be used by every manager
initialized after the Config.
.. code-block:: python
>>> from psengine.config import Config, get_config
# Name & version of the integration itself
>>> APP_ID = 'example-app/1.0.0'
# Name & version of the tool this integrates with (Optional)
>>> PLATFORM_ID = 'PSE/1.0.0'
>>> Config.init(rf_token='your_token', app_id=APP_ID, platform_id=PLATFORM_ID)
>>> config = get_config()
>>> config.app_id
'example-app/1.0.0'
The above will result in API calls made by the managers having the following headers set:
- 'X-RFToken' Header will contain the Recorded Future API Token
- 'User-Agent' Header will contain APP ID and Platform ID (if supplied) which is a Recorded Future requirement, which might look like this:
example-app/1.0.0 (macOS-14.1-arm64-arm-64bit) psengine-py/2.0.1 PSE/1.0.0
Authorization
--------------------------------------------------
In the example above we saw a token passed to the Config by the caller, but you can also omit the token during initialization and let
Config retrieve it from the environment variable `RF_TOKEN`. Just ensure that the environment variable is set before running your program:
export RF_TOKEN=your_token
Alternatively, if you want to set an rf_token separately for a single manager, you may pass it in the constructor:
.. code-block:: python
>>> note_mgr = AnalystNoteMgr(rf_token='your_token')
Logging
--------------------------------------------------
PSEngine also provides the capability for logging to console and files. If your program needs to show log output on the terminal and keep a .log file, just import and use psengine’s logger:
.. code-block:: python
>>> from psengine.logger import RFLogger
>>> LOG = RFLogger().get_logger()
>>> LOG.info('Hello, world!')
On the other hand, if your program’s log statements already have handlers setup, just log the normal way:
.. code-block:: python
>>> import logging
>>> LOG = logging.getLogger(__name__)
>>> LOG.info('Hello, world!')
In the second example, nothing is printed to terminal or file unless a handler is setup by another program running your code.
Proxies
--------------------------------------------------
If your environment requires a proxy to access the internet, you can set the proxy in the Config:
.. code-block:: python
>>> Config.init(
app_id=APP_ID,
platform_id=PLATFORM_ID,
http_proxy='http://proxy:8080',
https_proxy='http://proxy:8080',
client_ssl_verify=False,
)
Examples
--------------------------------------------------
Please refer to `examples <examples>`_ for usage example of each module.
Raw data
{
"_id": null,
"home_page": null,
"name": "psengine",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.9",
"maintainer_email": null,
"keywords": "API, Recorded Future, Cyber Security Engineering, Threat Intelligence",
"author": null,
"author_email": "Moise Medici <moise.medici@recordedfuture.com>, Patrick Kinsella <patrick.kinsella@recordedfuture.com>, Ernest Bartosevic <ernest.bartosevic@recordedfuture.com>",
"download_url": "https://files.pythonhosted.org/packages/fa/19/b319929cc2a57376eb19d7245c7f004e50c98c575328f840c260490b6665/psengine-2.1.1.tar.gz",
"platform": null,
"description": "==================================================\nPSEngine\n==================================================\n**PSEngine** is a simple, yet elegant, library for rapid development of integrations with Recorded Future.\n\n\n.. code-block:: python\n\n >>> from psengine.enrich import LookupMgr\n >>> lookup_mgr = LookupMgr(rf_token='token')\n >>> domain = lookup_mgr.lookup('cpejcogzznpudbsmaxxm.com', 'domain')\n >>> domain\n 'EnrichedDomain: cpejcogzznpudbsmaxxm.com, Risk Score: 20, Last Seen: 2024-07-22 02:50:59PM'\n >>> domain.entity\n 'cpejcogzznpudbsmaxxm.com'\n >>> domain.content.risk\n EntityRisk(criticality_label='Unusual', risk_string='4/52', score=20, rules=4...)\n >>> domain.content.risk.score\n 20\n >>> \n domain.content.risk.risk_summary\n '4 of 52 Risk Rules currently observed.'\n\n\nPSEngine allows you to interact with the Recorded Future API extremely easily. There\u2019s no need to manually build the URLs and query parameters - but nowadays, just use the modules dedicated to individual API endpoints!\n\nPSEngine is a Python package solely built and maintained by the Cyber Security Engineering team powering a number of high profile integrations, such as: Elasticsearch, QRadar, Anomali, Jira, TheHive, etc..\n\n\nInstallation\n==================================================\nPSEngine is a Python package that can be installed using pip. To install PSengine, run the following command:\n\n.. code-block:: bash\n\n $ pip install psengine\n\n\nPSEngine officially supports Python >= 3.9, < 3.14\n\n\nSupported Features & Best\u2013Practices\n==================================================\n\nPSEngine is ready for the demands of building robust and reliable integrations.\n\n* Collective Insights\n* Analyst Notes\n* Classic & Playbook Alerts\n* Risklists\n* On demand IOC enrichment\n* List management\n* Detection Rules\n* Built in logging\n* Easy configuration management\n* Proxy support\n\n\nQuick Start\n==================================================\nExcited, to get started? \n\nThe section below will give you the basic building blocks to start building integrations with PSEngine.\n\nBut first ensure that:\n\n- PSEngine is installed\n- PSEngine is up-to-date\n\nLet\u2019s get started with some core concepts and practices.\n\nConfig Management\n--------------------------------------------------\nThe key requirement when building integrations with PSEngine is initializing `Config` as early as possible in your program,\nbefore initializing any PSEngine managers. This way `rf_token` `app_id` and `platform_id` you set will be used by every manager\ninitialized after the Config.\n\n.. code-block:: python\n\n >>> from psengine.config import Config, get_config\n # Name & version of the integration itself\n >>> APP_ID = 'example-app/1.0.0'\n # Name & version of the tool this integrates with (Optional)\n >>> PLATFORM_ID = 'PSE/1.0.0'\n >>> Config.init(rf_token='your_token', app_id=APP_ID, platform_id=PLATFORM_ID)\n >>> config = get_config()\n >>> config.app_id\n 'example-app/1.0.0'\n\nThe above will result in API calls made by the managers having the following headers set:\n\n- 'X-RFToken' Header will contain the Recorded Future API Token\n- 'User-Agent' Header will contain APP ID and Platform ID (if supplied) which is a Recorded Future requirement, which might look like this:\n\n example-app/1.0.0 (macOS-14.1-arm64-arm-64bit) psengine-py/2.0.1 PSE/1.0.0\n \nAuthorization\n--------------------------------------------------\nIn the example above we saw a token passed to the Config by the caller, but you can also omit the token during initialization and let\nConfig retrieve it from the environment variable `RF_TOKEN`. Just ensure that the environment variable is set before running your program:\n\n export RF_TOKEN=your_token\n\nAlternatively, if you want to set an rf_token separately for a single manager, you may pass it in the constructor:\n\n.. code-block:: python\n\n >>> note_mgr = AnalystNoteMgr(rf_token='your_token')\n\nLogging\n--------------------------------------------------\nPSEngine also provides the capability for logging to console and files. If your program needs to show log output on the terminal and keep a .log file, just import and use psengine\u2019s logger:\n\n.. code-block:: python\n\n >>> from psengine.logger import RFLogger\n >>> LOG = RFLogger().get_logger()\n >>> LOG.info('Hello, world!')\n\nOn the other hand, if your program\u2019s log statements already have handlers setup, just log the normal way:\n\n.. code-block:: python\n\n >>> import logging\n >>> LOG = logging.getLogger(__name__)\n >>> LOG.info('Hello, world!')\n\nIn the second example, nothing is printed to terminal or file unless a handler is setup by another program running your code.\n\nProxies\n--------------------------------------------------\nIf your environment requires a proxy to access the internet, you can set the proxy in the Config:\n\n.. code-block:: python\n\n >>> Config.init(\n app_id=APP_ID,\n platform_id=PLATFORM_ID,\n http_proxy='http://proxy:8080',\n https_proxy='http://proxy:8080',\n client_ssl_verify=False,\n )\n\nExamples\n--------------------------------------------------\nPlease refer to `examples <examples>`_ for usage example of each module.\n",
"bugtrack_url": null,
"license": null,
"summary": "psengine is a simple, yet elegant, library for rapid development of integrations with Recorded Future.",
"version": "2.1.1",
"project_urls": {
"Changelog": "https://recordedfuture-professionalservices.github.io/psengine/CHANGELOG/",
"Homepage": "https://github.com/RecordedFuture-ProfessionalServices/psengine"
},
"split_keywords": [
"api",
" recorded future",
" cyber security engineering",
" threat intelligence"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2c34e6630a559665272cc49735d78787e612ce417c41c4af05ec14505f98f2e7",
"md5": "01f2b09f9349ca4b4931350936518eee",
"sha256": "1f9107196fe3758bec86bbe92a41cf90871a8694b8cb35fffca637ae4ce8781d"
},
"downloads": -1,
"filename": "psengine-2.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "01f2b09f9349ca4b4931350936518eee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.9",
"size": 210731,
"upload_time": "2025-08-22T13:48:33",
"upload_time_iso_8601": "2025-08-22T13:48:33.252279Z",
"url": "https://files.pythonhosted.org/packages/2c/34/e6630a559665272cc49735d78787e612ce417c41c4af05ec14505f98f2e7/psengine-2.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fa19b319929cc2a57376eb19d7245c7f004e50c98c575328f840c260490b6665",
"md5": "f6eb226deb83a77dafcb785b13e340f1",
"sha256": "2eef401b1e9d2181d163ce81ef036a10d4ead2117a6fb12829e936a01f763d96"
},
"downloads": -1,
"filename": "psengine-2.1.1.tar.gz",
"has_sig": false,
"md5_digest": "f6eb226deb83a77dafcb785b13e340f1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.9",
"size": 120139,
"upload_time": "2025-08-22T13:48:34",
"upload_time_iso_8601": "2025-08-22T13:48:34.919730Z",
"url": "https://files.pythonhosted.org/packages/fa/19/b319929cc2a57376eb19d7245c7f004e50c98c575328f840c260490b6665/psengine-2.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-22 13:48:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RecordedFuture-ProfessionalServices",
"github_project": "psengine",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "psengine"
}
JSON
