Thinking. Writing. Philosophising.

Email Github LinkedIn

VMware VeloCloud SD-WAN Orchestrator API: Automated Enterprise Events Retrieval for Network SLM, SIEM and SOAR Integration

Posted on November 24, 2021 — 6 Minutes Read

Building upon the success of Software Defined Network (SDN) that takes advantage of the programmability and the agile and iterative development of software for a logical overlay network, that responds to the real-time network status and the type of applications traversing in it by separating the control function from the forwarding one, the Wide Area Network (WAN) has been steadily transformed from a hardware-defined infrastructure, built on top of purpose-built equipment and point-to-point circuits, to a Software Defined WAN (SD-WAN) that is transport-agnostic, application-centric and that routes network traffic with respect to the real-time network status and the service levels required by the respective applications. While open standard is the norm in an increasingly software defined world, for staying ahead of the competition in this lucrative enterprise networking market, most vendors develop and implement their SD-WAN solutions differently, which results in incompatible solutions between vendors and a dangerous vendor lock-in, that is increasingly alarming for enterprises.

Non-interoperability notwithstanding, as a software-centric networking solution, these vendor-defined SD-WAN implementations often provide a set of Application Programmable Interface (API) for interacting with other software systems, that not only allows them to be integrated with the existing Network Service Level Management (SLM) system, and Security Information and Event Management (SIEM) or Security Orchestration, Automation and Response (SOAR) platforms, down the road perhaps it will allow these various vendor implementations to operate alongside one and another in a single logical overlay network that fulfils the promise and the premise of SD-WAN. While that is still to come, what follows will be a Python app that calls the VMware VeloCloud SD-WAN Orchestrator (VCO) API for an automated retrieval of the enterprise events of all of the SD-WAN Edges in the enterprise network for system integration. The rest of the code is containerised with Docker Compose for a modular and cloud-native deployment that fits in any microservice architecture, and is shared on Github for reference and further development. With the Python app containerised with Docker Compose, deployment is as simple as:

  1. Download a copy of the app;
  2. Create the environment variables for the VCO authentication and modify the crontab if needed; and
  3. Docker Compose or build and run the image manually to start the app, or alternatively run the Python script as a standalone service.

See also:

Git Clone

Download a copy of the app with git clone. Be sure to pass the --recurse-submodules argument to initialise and update each submodule in the repository.

$ git clone --recurse-submodules https://github.com/kurtcms/vco-api-ent-event /app/vco-api-ent-event/

Environment Variables

The app expects the hostname, the API token or the username and password for the VCO, as environment variables in a .env file in the same directory.

Should both the API token, and the username and password, for the VCO be present, the app will always use the API token.

Be sure to create the .env file.

$ nano /app/vco-api-ent-event/.env

And define the credentials accordingly.

VCO_HOSTNAME = 'vco.managed-sdwan.com/'

# Either the API token
VCO_TOKEN = '(redacted)'

# Or the username and password
VCO_USERNAME = 'kurtcms'
VCO_PASSWORD = '(redacted)'


By default the app is scheduled with cron to retrieve the enterprise events every 15 minutes, with stdout and stderr redirected to the main process for Docker logs.

Modify the crontab if a different schedule is required.

$ nano /app/vco-api-ent-event/crontab

Docker Container

Packaged as a container, the app is a standalone, executable package that may be run on Docker Engine. Be sure to have Docker installed.

Docker Compose

With Docker Compose, the app may be provisioned with a single command.

Install Docker and Docker Compose with the Bash script that comes with app.

$ chmod +x /app/vco-api-ent-event/docker-compose/docker-compose.sh \
    && /app/vco-api-ent-event/docker-compose/docker-compose.sh

Start the containers with Docker Compose.

$ docker-compose -f /app/vco-api-ent-event/docker-compose.yml up -d

Stopping the container is as simple as a single command.

$ docker-compose -f /app/vco-api-ent-event/docker-compose.yml down

Build and Run

Otherwise the Docker image can also be built manually.

$ docker build -t vco_api_ent_event /app/vco-api-ent-event/

Run the image with Docker once it is ready.

$ docker run -it --rm --name vco_api_ent_event vco_api_ent_event

Standalone Python Script

Alternatively the vco_api_ent_event.py script may be deployed as a standalone service.


In which case be sure to install the following required libraries for the vco_api_main.py:

  1. Requests
  2. Python-dotenv
  3. NumPy
  4. pandas

Install them with pip3:

$ pip3 install requests python-dotenv numpy pandas


The script may then be executed with a task scheduler such as cron that runs it once every 15 minutes for example.

$ (crontab -l; echo "*/15 * * * * /usr/bin/python3 /app/vco-api-ent-event/vco_api_ent_event.py") | crontab -

Enterprise Event in JSON

The enterprise events will be appended to a JSON file, with each in a new line, on a Docker volume that is mounted in the same directory of the docker-compose.yml file on the Docker host. If the Python script is run as a standalone service, the JSON file will be in the same directory of the script instead.

{"id": 2913202, "eventTime": "2021-10-23T06:48:57.000Z", "event": "VPN_DATACENTER_STATUS", "category": "SYSTEM", "severity": "NOTICE", "message": "Tunnel to [Azure-SIN] - Failed to negotiate child SA IKEv2_I with Error: ERR_IKE_TIMEOUT", "detail": "{\"enterpriseLogicalId\": \"24676352-23ed-4cdd-a0db-52f61810de1b\", \"dataCenterLogicalId\": \"bb395d4c-5963-4d14-8e6d-c2822c9dfadc\", \"ipAddress\": \"\", \"ikeState\": \"DOWN\", \"numberP2SA\": 0, \"Hint\": \"No response from peer or no proposal chosen; check VPN type, GWIP, DH Group, IKE-ID, subnets.\"}", "enterpriseUsername": null, "edgeName": null, "segmentName": null}

In any case, the JSON file is stored under a directory by the enterpriseName to ease access.

└── enterpriseName/
    └── events.json


Software should be open source and standardised for it to tap into the infinite wisdom of the community for iterative feature development and security enhancement. It does not necessarily mean that commercial organisation will then not be able to profit from it, for there are countless examples of companies, such as Canonical with its Ubuntu Linux Operating System (OS) and Google Cloud with its Google Kubernetes Engine (GKE), that earn a fair profit from opening sourcing their software, while providing business-grade technical support or Platform as a Service (PaaS) for a fee, that others deploying the software for commercial use will be more than delighted to pay. That said, SD-WAN for historical reasons was off on a different path, and it remains to be seen that whether the API by these various vendor implementations is the first step towards an open standard or the last.