*This library is currently being beta-tested. See something that's broken? Did we get something
wrong? [Create an issue and let us know!][issues]*
<p align="center">
<a id="ibeam" href="#ibeam">
<img src="https://github.com/Voyz/ibeam/blob/master/media/ibeam_logo.png" alt="IBeam logo" title="IBeam logo" width="600"/>
</a>
</p>
<p align="center">
<a href="https://opensource.org/licenses/Apache-2.0">
<img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg"/>
</a>
<a href="https://github.com/Voyz/ibeam/releases">
<img src="https://img.shields.io/pypi/v/ibeam?label=version"/>
</a>
</p>
IBeam is an authentication and maintenance tool used for
the [Interactive Brokers Client Portal Web API Gateway.][gateway]
Features:
* **Facilitates continuous headless run of the Gateway.**
* **No physical display required** - virtual display buffer can be used instead.
* **No interaction from the user required** - automated injection of IBKR credentials into the authentication page used
by the Gateway.
* **TLS certificate support** - you can provide your own certificates.
* **Containerised using Docker** - it's a plug and play image, although IBeam can be used as standalone too.
* **Not so secure** - Yupp, you'll need to store the credentials somewhere, and that's a risk. Read more about it
in [Security](#security).
**NOTE**: IBeam is not designed to automate logging into TWS or IB Gateway (also known as TWS Gateway). Use [IBC](ibc) for that.
There are also [Docker image projects that include TWS/Gateway and IBC](ib-gateway-docker).
## Documentation:
* Setup
* [Installation and Startup][installation-and-startup]
* [Runtime Environment][runtime-environment]
* Advanced
* [Inputs And Outputs][inputs-and-outputs]
* [IBeam Configuration][ibeam-configuration]
* [Gateway Configuration][gateway-configuration]
* [TLS Certificates and HTTPS][tls-and-https]
* [Two Factor Authentication][two-fa]
* More
* [Troubleshooting][troubleshooting]
<a href="https://www.youtube.com/watch?v=603n4xV26S0">
<img src="https://github.com/Voyz/voyz_public/blob/master/ibeam_promo_vidA_A01.gif" alt="IBeam showcase gif" title="IBeam showcase gif" width="500"/>
</a>
## Quick start
### Installation
#### Docker Image (Recommended):
```posh
docker pull voyz/ibeam
```
#### Standalone:
```posh
pip install ibeam
```
### Startup
#### Docker
```posh
docker run --env IBEAM_ACCOUNT=your_account123 --env IBEAM_PASSWORD=your_password123 -p 5000:5000 voyz/ibeam
```
#### docker-compose:
Create a `docker-compose.yml` file with the following contents:
```yaml
version: "2.1"
services:
ibeam:
image: voyz/ibeam
container_name: ibeam
env_file:
- env.list
ports:
- 5000:5000
- 5001:5001
network_mode: bridge # Required due to clientportal.gw IP whitelist
restart: 'no' # Prevents IBEAM_MAX_FAILED_AUTH from being exceeded
```
Create an `env.list` file in the same directory with the following contents:
```posh
IBEAM_ACCOUNT=your_account123
IBEAM_PASSWORD=your_password123
```
Run the following command:
```posh
docker-compose up -d
```
#### Standalone:
```posh
python ibeam_starter.py
```
----
Once started, verify the Gateway is running by calling:
```posh
curl -X GET "https://localhost:5000/v1/api/one/user" -k
```
Read more in [Installation and Startup][installation-and-startup] and [Advanced Secrets][advanced-secrets].
## <a name="how-ibeam-works"></a>How does IBeam work?
In a standard startup IBeam performs the following:
1. **Copy inputs** from the Inputs Directory to Gateway's `root` folder (if provided).
1. **Ensure the Gateway is running** by calling the tickle endpoint. If not:
1. Start the Gateway in a new shell.
1. **Ensure the Gateway has an active session that is authenticated** by calling the tickle endpoint. If not:
1. Create a new Chrome Driver instance using `selenium`.
1. Start a virtual display using `pyvirtualdisplay`.
1. Access the Gateway's authentication website.
1. Once loaded, input username and password and submit the form.
1. Wait for the login confirmation and quit the website.
1. Verify once again if Gateway is running and authenticated.
1. **Start the maintenance**, attempting to keep the Gateway alive and authenticated. Will repeat login if finds no
active session or the session is not authenticated.
## <a name="security"></a>Security
Please feel free to suggest improvements to the security risks currently present in IBeam and the Gateway
by [opening an issue][issues] on GitHub.
### Credentials
The Gateway requires credentials to be provided on a regular basis. The only way to avoid manually having to input them
every time is to store the credentials somewhere. This alone is a security risk.
By default, IBeam expects the credentials to be available as environment variables during runtime. Whether running IBeam
in a container or directly on a host machine, an unwanted user may gain access to these credentials. If your setup is
exposed to a risk of someone unauthorised reading the credentials, you may want to look for other solutions than IBeam
or use the Gateway standalone and authenticate manually each time.
There are currently two proposed solutions to this problem:
1. **Docker Swarm**
You can remove one of the attack vectors by using a locked Docker Swarm instance, installing your credentials into it using Docker Secrets, and telling IBeam to read the secrets from the container's in-memory `/run` filesystem.
This configuration allows the credentials to be encrypted when at rest.
But the credentials are still accessible in plaintext via the running container, so if a security issue arises where an exploit exists for the port 5000 API, or if your host is compromised and an attacker can access your running container, then the secret could be exposed.
2. **GCP Secret Manager**
If you're deploying IBeam on Google Cloud Platform, you can securely use the Service Account's credentials to access [GCP Secret Manager][secret-manager-docs]. This is possible since all types of GCP deployment (currently: Compute Engine, Kubernetes, Cloud Run and Cloud Functions) are running within a context that has a Service Account available. IBeam can query Google's metadata server when running on GCP for the Service Account's access token, and use that to read secrets from the Secret Manager.
See [Advanced Secrets][advanced-secrets] for more information.
## Roadmap
IBeam was built by traders just like you. We made it open source in order to collectively build a reliable solution. If
you enjoy using IBeam, we encourage you to attempt implementing one of the following tasks:
* ~~Include TLS certificates.~~
* ~~Two Factor Authentictaion.~~
* Remove necessity to install Java.
* ~~Remove necessity to install Chrome or find a lighter replacement.~~
* Add usage examples.
* Full test coverage.
* ~~Improve the security issues.~~
* Find a lighter replacement to using Chromium
Read the [CONTRIBUTING](https://github.com/Voyz/ibeam/blob/master/CONTRIBUTING.md) guideline to get started.
----
## Licence
See [LICENSE](https://github.com/Voyz/ibeam/blob/master/LICENSE)
## Disclaimer
IBeam is not built, maintained, or endorsed by the Interactive Brokers.
Use at own discretion. IBeam and its authors give no guarantee of uninterrupted run of and access to the Interactive
Brokers Client Portal Web API Gateway. You should prepare for breaks in connectivity to IBKR servers and should not
depend on continuous uninterrupted run of the Gateway. IBeam requires your private credentials to be exposed to a
security risk, potentially resulting in, although not limited to interruptions, loss of capital and loss of access to
your account. To partially reduce the potential risk use Paper Account credentials.
IBeam is provided on an AS IS and AS AVAILABLE basis without any representation or endorsement made and without warranty
of any kind whether express or implied, including but not limited to the implied warranties of satisfactory quality,
fitness for a particular purpose, non-infringement, compatibility, security and accuracy. To the extent permitted by
law, IBeam's authors will not be liable for any indirect or consequential loss or damage whatever (including without
limitation loss of business, opportunity, data, profits) arising out of or in connection with the use of IBeam. IBeam's
authors make no warranty that the functionality of IBeam will be uninterrupted or error free, that defects will be
corrected or that IBeam or the server that makes it available are free of viruses or anything else which may be harmful
or destructive.
## Built by Voy
Hi! Thanks for checking out and using this library. If you are interested in discussing your project, require
mentorship, consider hiring me, or just wanna chat - I'm happy to talk.
You can send me an email to get in touch: hello@voyzan.com
Or if you'd just want to give something back, I've got a Buy Me A Coffee account:
<a href="https://www.buymeacoffee.com/voyzan" rel="nofollow">
<img src="https://raw.githubusercontent.com/Voyz/voyz_public/master/vz_BMC.png" alt="Buy Me A Coffee" style="max-width:100%;" width="192">
</a>
Thanks and have an awesome day 👋
[home]: https://github.com/Voyz/ibeam/wiki
[installation-and-startup]: https://github.com/Voyz/ibeam/wiki/Installation-and-startup
[runtime-environment]: https://github.com/Voyz/ibeam/wiki/Runtime-environment
[ibeam-configuration]: https://github.com/Voyz/ibeam/wiki/IBeam-Configuration
[gateway-configuration]: https://github.com/Voyz/ibeam/wiki/Gateway-Configuration
[inputs-and-outputs]: https://github.com/Voyz/ibeam/wiki/Inputs-And-Outputs
[two-fa]: https://github.com/Voyz/ibeam/wiki/Two-Factor-Authentication
[tls-and-https]: https://github.com/Voyz/ibeam/wiki/TLS-Certificates-and-HTTPS
[advanced-secrets]: https://github.com/Voyz/ibeam/wiki/Advanced-Secrets
[troubleshooting]: https://github.com/Voyz/ibeam/wiki/Troubleshooting
[issues]: https://github.com/Voyz/ibeam/issues
[gateway]: https://ibkrcampus.com/ibkr-api-page/webapi-doc/
[ibc]: https://github.com/IbcAlpha/IBC
[ib-gateway-docker]: https://github.com/UnusualAlpha/ib-gateway-docker
[secret-manager-docs]: https://cloud.google.com/secret-manager/docs
Raw data
{
"_id": null,
"home_page": "https://github.com/Voyz/ibeam",
"name": "ibeam",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "interactive brokers, algo trading, algorithmic trading, data flow, quant, trading",
"author": "Voy Zan",
"author_email": "voy1982@yahoo.co.uk",
"download_url": "https://files.pythonhosted.org/packages/29/18/da4eddbc497dc22c0dfb87f2bcccb9ddb4dc1278cff5ec07c9a06df4913d/ibeam-0.5.3.tar.gz",
"platform": null,
"description": "*This library is currently being beta-tested. See something that's broken? Did we get something\r\nwrong? [Create an issue and let us know!][issues]*\r\n\r\n<p align=\"center\">\r\n <a id=\"ibeam\" href=\"#ibeam\">\r\n <img src=\"https://github.com/Voyz/ibeam/blob/master/media/ibeam_logo.png\" alt=\"IBeam logo\" title=\"IBeam logo\" width=\"600\"/>\r\n </a>\r\n</p>\r\n\r\n<p align=\"center\">\r\n <a href=\"https://opensource.org/licenses/Apache-2.0\">\r\n <img src=\"https://img.shields.io/badge/License-Apache%202.0-blue.svg\"/> \r\n </a>\r\n <a href=\"https://github.com/Voyz/ibeam/releases\">\r\n <img src=\"https://img.shields.io/pypi/v/ibeam?label=version\"/> \r\n </a>\r\n</p>\r\n\r\nIBeam is an authentication and maintenance tool used for\r\nthe [Interactive Brokers Client Portal Web API Gateway.][gateway]\r\n\r\nFeatures:\r\n\r\n* **Facilitates continuous headless run of the Gateway.**\r\n\r\n* **No physical display required** - virtual display buffer can be used instead.\r\n* **No interaction from the user required** - automated injection of IBKR credentials into the authentication page used\r\n by the Gateway.\r\n* **TLS certificate support** - you can provide your own certificates.\r\n* **Containerised using Docker** - it's a plug and play image, although IBeam can be used as standalone too.\r\n* **Not so secure** - Yupp, you'll need to store the credentials somewhere, and that's a risk. Read more about it\r\n in [Security](#security).\r\n\r\n**NOTE**: IBeam is not designed to automate logging into TWS or IB Gateway (also known as TWS Gateway). Use [IBC](ibc) for that.\r\nThere are also [Docker image projects that include TWS/Gateway and IBC](ib-gateway-docker).\r\n\r\n## Documentation:\r\n\r\n* Setup\r\n * [Installation and Startup][installation-and-startup]\r\n * [Runtime Environment][runtime-environment]\r\n* Advanced\r\n * [Inputs And Outputs][inputs-and-outputs]\r\n * [IBeam Configuration][ibeam-configuration]\r\n * [Gateway Configuration][gateway-configuration]\r\n * [TLS Certificates and HTTPS][tls-and-https]\r\n * [Two Factor Authentication][two-fa]\r\n* More\r\n * [Troubleshooting][troubleshooting]\r\n\r\n<a href=\"https://www.youtube.com/watch?v=603n4xV26S0\">\r\n <img src=\"https://github.com/Voyz/voyz_public/blob/master/ibeam_promo_vidA_A01.gif\" alt=\"IBeam showcase gif\" title=\"IBeam showcase gif\" width=\"500\"/>\r\n</a>\r\n\r\n## Quick start\r\n\r\n### Installation\r\n\r\n#### Docker Image (Recommended):\r\n\r\n```posh\r\ndocker pull voyz/ibeam\r\n```\r\n\r\n#### Standalone:\r\n\r\n```posh\r\npip install ibeam\r\n```\r\n\r\n### Startup\r\n\r\n#### Docker\r\n\r\n```posh\r\ndocker run --env IBEAM_ACCOUNT=your_account123 --env IBEAM_PASSWORD=your_password123 -p 5000:5000 voyz/ibeam\r\n```\r\n\r\n#### docker-compose:\r\n\r\nCreate a `docker-compose.yml` file with the following contents:\r\n\r\n```yaml\r\nversion: \"2.1\"\r\n\r\nservices:\r\n ibeam:\r\n image: voyz/ibeam\r\n container_name: ibeam\r\n env_file:\r\n - env.list\r\n ports:\r\n - 5000:5000\r\n - 5001:5001\r\n network_mode: bridge # Required due to clientportal.gw IP whitelist\r\n restart: 'no' # Prevents IBEAM_MAX_FAILED_AUTH from being exceeded\r\n```\r\n\r\nCreate an `env.list` file in the same directory with the following contents:\r\n\r\n```posh\r\nIBEAM_ACCOUNT=your_account123\r\nIBEAM_PASSWORD=your_password123\r\n```\r\n\r\nRun the following command:\r\n\r\n```posh\r\ndocker-compose up -d\r\n```\r\n\r\n#### Standalone:\r\n\r\n```posh\r\npython ibeam_starter.py\r\n```\r\n\r\n----\r\nOnce started, verify the Gateway is running by calling:\r\n\r\n```posh\r\ncurl -X GET \"https://localhost:5000/v1/api/one/user\" -k\r\n```\r\n\r\nRead more in [Installation and Startup][installation-and-startup] and [Advanced Secrets][advanced-secrets].\r\n\r\n## <a name=\"how-ibeam-works\"></a>How does IBeam work?\r\n\r\nIn a standard startup IBeam performs the following:\r\n\r\n1. **Copy inputs** from the Inputs Directory to Gateway's `root` folder (if provided).\r\n1. **Ensure the Gateway is running** by calling the tickle endpoint. If not:\r\n 1. Start the Gateway in a new shell.\r\n1. **Ensure the Gateway has an active session that is authenticated** by calling the tickle endpoint. If not:\r\n 1. Create a new Chrome Driver instance using `selenium`.\r\n 1. Start a virtual display using `pyvirtualdisplay`.\r\n 1. Access the Gateway's authentication website.\r\n 1. Once loaded, input username and password and submit the form.\r\n 1. Wait for the login confirmation and quit the website.\r\n 1. Verify once again if Gateway is running and authenticated.\r\n1. **Start the maintenance**, attempting to keep the Gateway alive and authenticated. Will repeat login if finds no\r\n active session or the session is not authenticated.\r\n\r\n## <a name=\"security\"></a>Security\r\n\r\nPlease feel free to suggest improvements to the security risks currently present in IBeam and the Gateway\r\nby [opening an issue][issues] on GitHub.\r\n\r\n### Credentials\r\n\r\nThe Gateway requires credentials to be provided on a regular basis. The only way to avoid manually having to input them\r\nevery time is to store the credentials somewhere. This alone is a security risk.\r\n\r\nBy default, IBeam expects the credentials to be available as environment variables during runtime. Whether running IBeam\r\nin a container or directly on a host machine, an unwanted user may gain access to these credentials. If your setup is\r\nexposed to a risk of someone unauthorised reading the credentials, you may want to look for other solutions than IBeam\r\nor use the Gateway standalone and authenticate manually each time.\r\n\r\nThere are currently two proposed solutions to this problem:\r\n\r\n1. **Docker Swarm**\r\n\r\n You can remove one of the attack vectors by using a locked Docker Swarm instance, installing your credentials into it using Docker Secrets, and telling IBeam to read the secrets from the container's in-memory `/run` filesystem.\r\n This configuration allows the credentials to be encrypted when at rest. \r\n But the credentials are still accessible in plaintext via the running container, so if a security issue arises where an exploit exists for the port 5000 API, or if your host is compromised and an attacker can access your running container, then the secret could be exposed. \r\n2. **GCP Secret Manager**\r\n\r\n If you're deploying IBeam on Google Cloud Platform, you can securely use the Service Account's credentials to access [GCP Secret Manager][secret-manager-docs]. This is possible since all types of GCP deployment (currently: Compute Engine, Kubernetes, Cloud Run and Cloud Functions) are running within a context that has a Service Account available. IBeam can query Google's metadata server when running on GCP for the Service Account's access token, and use that to read secrets from the Secret Manager.\r\n\r\n\r\nSee [Advanced Secrets][advanced-secrets] for more information.\r\n\r\n## Roadmap\r\n\r\nIBeam was built by traders just like you. We made it open source in order to collectively build a reliable solution. If\r\nyou enjoy using IBeam, we encourage you to attempt implementing one of the following tasks:\r\n\r\n* ~~Include TLS certificates.~~\r\n* ~~Two Factor Authentictaion.~~\r\n* Remove necessity to install Java.\r\n* ~~Remove necessity to install Chrome or find a lighter replacement.~~\r\n* Add usage examples.\r\n* Full test coverage.\r\n* ~~Improve the security issues.~~\r\n* Find a lighter replacement to using Chromium\r\n\r\nRead the [CONTRIBUTING](https://github.com/Voyz/ibeam/blob/master/CONTRIBUTING.md) guideline to get started.\r\n\r\n----\r\n\r\n## Licence\r\n\r\nSee [LICENSE](https://github.com/Voyz/ibeam/blob/master/LICENSE)\r\n\r\n## Disclaimer\r\n\r\nIBeam is not built, maintained, or endorsed by the Interactive Brokers.\r\n\r\nUse at own discretion. IBeam and its authors give no guarantee of uninterrupted run of and access to the Interactive\r\nBrokers Client Portal Web API Gateway. You should prepare for breaks in connectivity to IBKR servers and should not\r\ndepend on continuous uninterrupted run of the Gateway. IBeam requires your private credentials to be exposed to a\r\nsecurity risk, potentially resulting in, although not limited to interruptions, loss of capital and loss of access to\r\nyour account. To partially reduce the potential risk use Paper Account credentials.\r\n\r\nIBeam is provided on an AS IS and AS AVAILABLE basis without any representation or endorsement made and without warranty\r\nof any kind whether express or implied, including but not limited to the implied warranties of satisfactory quality,\r\nfitness for a particular purpose, non-infringement, compatibility, security and accuracy. To the extent permitted by\r\nlaw, IBeam's authors will not be liable for any indirect or consequential loss or damage whatever (including without\r\nlimitation loss of business, opportunity, data, profits) arising out of or in connection with the use of IBeam. IBeam's\r\nauthors make no warranty that the functionality of IBeam will be uninterrupted or error free, that defects will be\r\ncorrected or that IBeam or the server that makes it available are free of viruses or anything else which may be harmful\r\nor destructive.\r\n\r\n## Built by Voy\r\n\r\nHi! Thanks for checking out and using this library. If you are interested in discussing your project, require\r\nmentorship, consider hiring me, or just wanna chat - I'm happy to talk.\r\n\r\nYou can send me an email to get in touch: hello@voyzan.com\r\n\r\nOr if you'd just want to give something back, I've got a Buy Me A Coffee account:\r\n\r\n<a href=\"https://www.buymeacoffee.com/voyzan\" rel=\"nofollow\">\r\n <img src=\"https://raw.githubusercontent.com/Voyz/voyz_public/master/vz_BMC.png\" alt=\"Buy Me A Coffee\" style=\"max-width:100%;\" width=\"192\">\r\n</a>\r\n\r\nThanks and have an awesome day \u00f0\u0178\u2018\u2039\r\n\r\n[home]: https://github.com/Voyz/ibeam/wiki\r\n\r\n[installation-and-startup]: https://github.com/Voyz/ibeam/wiki/Installation-and-startup\r\n\r\n[runtime-environment]: https://github.com/Voyz/ibeam/wiki/Runtime-environment\r\n\r\n[ibeam-configuration]: https://github.com/Voyz/ibeam/wiki/IBeam-Configuration\r\n\r\n[gateway-configuration]: https://github.com/Voyz/ibeam/wiki/Gateway-Configuration\r\n\r\n[inputs-and-outputs]: https://github.com/Voyz/ibeam/wiki/Inputs-And-Outputs\r\n\r\n[two-fa]: https://github.com/Voyz/ibeam/wiki/Two-Factor-Authentication\r\n\r\n[tls-and-https]: https://github.com/Voyz/ibeam/wiki/TLS-Certificates-and-HTTPS\r\n\r\n[advanced-secrets]: https://github.com/Voyz/ibeam/wiki/Advanced-Secrets\r\n\r\n[troubleshooting]: https://github.com/Voyz/ibeam/wiki/Troubleshooting\r\n\r\n[issues]: https://github.com/Voyz/ibeam/issues\r\n\r\n[gateway]: https://ibkrcampus.com/ibkr-api-page/webapi-doc/\r\n\r\n[ibc]: https://github.com/IbcAlpha/IBC\r\n\r\n[ib-gateway-docker]: https://github.com/UnusualAlpha/ib-gateway-docker\r\n\r\n[secret-manager-docs]: https://cloud.google.com/secret-manager/docs\r\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "IBeam is an authentication and maintenance tool used for the Interactive Brokers Client Portal Web API Gateway.",
"version": "0.5.3",
"project_urls": {
"Homepage": "https://github.com/Voyz/ibeam"
},
"split_keywords": [
"interactive brokers",
" algo trading",
" algorithmic trading",
" data flow",
" quant",
" trading"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2918da4eddbc497dc22c0dfb87f2bcccb9ddb4dc1278cff5ec07c9a06df4913d",
"md5": "fc18bb131f760ac979de045c58f8e9f7",
"sha256": "046f95496bd741c72723345135aa0e4dc427aa1fd98cd7bac425d533133f3c78"
},
"downloads": -1,
"filename": "ibeam-0.5.3.tar.gz",
"has_sig": false,
"md5_digest": "fc18bb131f760ac979de045c58f8e9f7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 41500,
"upload_time": "2024-04-28T04:28:30",
"upload_time_iso_8601": "2024-04-28T04:28:30.231839Z",
"url": "https://files.pythonhosted.org/packages/29/18/da4eddbc497dc22c0dfb87f2bcccb9ddb4dc1278cff5ec07c9a06df4913d/ibeam-0.5.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-28 04:28:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Voyz",
"github_project": "ibeam",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "ibeam"
}
JSON
