pybanyan

API library and command-line interface for Banyan Security

Prerequisites

Python 3.7+ must be installed.

Installation

Installing the easy way

$ pip install pybanyan

Installing the hard way

$ git clone https://github.com/banyansecurity/pybanyan.git
$ cd pybanyan
$ pip install -r requirements.txt
$ python setup.py install --user

Usage

This package contains both an API client and a CLI tool. To use either one, you need to generate an API credential from the Banyan Command Center.

API library

Here's a sample script that uses the library to print the names of every hosted website service registered in Banyan:

from banyan.api import BanyanApiClient

c = BanyanApiClient()
for service in c.services_web.list():
    print(service.name)

Output:

$ python examples/list_services.py
jira
jupyter
kube
mysql
rds-mysql
rds-pgsql

The BanyanApiClient class accepts optional arguments to specify the API server and API credential. If not provided, it gets them from environment variables named BANYAN_API_URL and BANYAN_API_KEY (you can also use a personal refresh token as your API credential.

Full API documentation is available in the docs.

Banyan CLI tool

Before you use the CLI, create a file called ~/.banyan.conf in your home directory and paste in your API credential in the api_key field (you can also use a personal refresh token as your API credential):

[banyan]
api_url = https://net.banyanops.com
api_key = MY_API_KEY

The CLI is invoked with the banyan tool. It contains a number of commands and sub-commands to help you work with policies, roles, services, users, and other objects in Banyan.

Run the banyan tool by itself to see the available commands.

$ banyan
usage: banyan [options] <command> <subcommand> [<subcommand> ...] [parameters]

API library and command-line interface for Banyan Security

options:
  -h, --help            show this help message and exit
  -d, --debug           full application debug mode
  -q, --quiet           suppress all console output
  --version, -v         show program's version number and exit
  --api-url API_URL     URL for the Banyan API server. Can also be configured via the BANYAN_API_URL environment variable.
  --api-key API_KEY     API credential used for the authentication to the Banyan API server. Can also be configured via the BANYAN_API_KEY environment
                        variable.
  --insecure-tls, -k    Allow connections to API servers with invalid TLS certificates.
  --output-format {table,json,yaml}, -o {table,json,yaml}
                        desired output format (table, json, yaml)

Commands:
  {netagent,service,shield,access-tier,api-key,audit,cloud-resource,connector,device,event,export,policy,role,service-infra,service-tunnel,service-web,user}
    netagent            (deprecated: use access-tier) manage netagents
    service             (deprecated: use service-web or service-infra) manage web and TCP services and workloads
    shield              (deprecated) manage shield clusters
    access-tier         manage access tiers
    api-key             manage API keys
    audit               retrieve audit logs
    cloud-resource      manage cloud resources discovered from IaaS
    connector           manage connectors
    device              manage devices
    event               report on security events
    export              export all objects from an organization
    policy              manage authorization policies for users and workloads
    role                manage user and workload roles
    service-infra       manage infrastructure services
    service-tunnel      manage service tunnels
    service-web         manage hosted website services
    user                manage users

Each of the commands has multiple subcommands. For example, banyan service allows you to list services, create/delete, enable/disable, etc. Run the command without any subcommand to see the options:

$ banyan service-web
usage: banyan service-web [-h]
                      {attach-policy,create,delete,detach-policy,disable,enable,get,list,test,update}
                      ...

optional arguments:
  -h, --help            show this help message and exit

sub-commands:
  {attach-policy,create,delete,detach-policy,disable,enable,get,list,test,update}
    attach-policy       attach a policy to a service
    create              create a new service from a JSON specification
    delete              delete a service
    detach-policy       detach the active policy from a service
    disable             disable a service
    enable              enable a service
    get                 show the definition of a registered service
    list                list registered services
    test                run sanity checks on a service
    update              update an existing service from a JSON specification

To see the full help available for any command, just add the -h or --help option to the end of the command. For example:

$ banyan service-web attach-policy --help
usage: banyan service-web attach-policy [-h] [--permissive] [--enforcing]
                                    service_name_or_id policy_name_or_id

positional arguments:
  service_name_or_id  Name or ID of the service to attach a policy to.
  policy_name_or_id   Name or ID of the policy to attach to the service.

optional arguments:
  -h, --help          show this help message and exit
  --permissive        Set the policy to permissive mode (allow all traffic and
                      log any unauthorized access).
  --enforcing         Set the policy to enforcing mode (deny unauthorized
                      access).

Integrations

You can automate different types of workflows by integrating with external APIs. We provide pre-built integrations for 2 types of workflows:

1. Synchronize cloud resources from your IaaS provider

You can discover and synchronize your IaaS (Infrastructure As A Service) resources into Banyan's inventory, so you can later publish some or all of them as Banyan services. Read our overview on how Banyan synchronizes IaaS resources, and then check out instructions to set up for your specific IaaS provider:

• AWS
• Azure Cloud
• GCP
• Oracle Cloud

2. Bookmark Banyan services into your SSO catalog

You can publish Banyan services as bookmark applications in your SSO (Single Sign On) portal, so your end-user can access them via their SSO catalog. Check out the provider-specific link for setup instructions.

• Okta
• AzureAD

Development

To work on the pybanyan code, follow the instructions in the documentation.

Support

This API library and its accompanying CLI utility are provided free of charge and without support. To report issues with the library, please create a new issue in Github.

Contributions

We welcome your contributions in the form of pull requests! Please follow the standard Github pull request workflow.