NAV

API Reference

The VulcanoSec API is based on REST. It is designed to be easy and predictable and to have resource-oriented URL endpoints. It uses common HTTP verbs and response codes to indicate API errors. Therefore the API can be understood by standard HTTP clients and libraries. In general the API uses JSON as data input and output format.

API Endpoint For VulcanoSec Suite On-Premise:

https://hostname/api/

Authentication

Example

# Request an access token via

curl -X POST https://hostname/api/oauth/token \
  -u admin:flyingsheepwithwings \
  -d "grant_type=client_credentials"

It returns

{
  "access_token": "VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==",
  "expires_in": 79781,
  "token_type": "vulcanosec token"
}

HTTP Request

POST https://hostname/api/oauth/token

You need to send a ‘Authorization: Basic base64encodedpassword’ header with your username and password in order to retrieve a valid api token.

VulcanoSec uses API token to allow access to the API and expects for the API key to be included as HTTP Basic Authentication in all API requests to the server in a header that looks like the following:

Authorization: Basic VlMzeDFYU2c0SGsvd3h3OElQKzJYcG1vS3luUjd1cnhnbGFHZkxmRlJYYnhZbGp4Tlc1bWtzT1NOaitCa08yRFZvUWVoR29zQm5xQ0pBOFdBejNKeWc9PTo=

You need to provide your API key as the username like VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:. A password is not required. Basic Authentication uses the colon : to seperat between username and password.

// a method to generate the Basic header in JavaScript
// @see https://developer.mozilla.org/en-US/docs/Web/API/WindowBase64/btoa
var user = 'admin', pass = ''
btoa(user + ':' + pass)
// return "YWRtaW46"

For request authorization, use the following request scheme:

# With shell, you can just pass the correct header with each request
curl "https://hostname/api/version" \
  -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

{
  "api": "vulcanosec",
  "version": "1.0.1"
}

Compliance Profiles

List all compliance profiles of owner

# lists all compliance profiles of a user
curl  "https://hostname/api/owners/vulcanosec/compliance" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

{
    "linux": {
        "id": "linux",
        "owner": "vulcanosec",
        "name": "vulcanosec/linux",
        "title": "Basic Linux",
        "version": "1.0.0",
        "summary": "Verify that Linux nodes are configured securely",
        "description": "# Basic Linux Compliance Profile\n\ncopyright: 2015, Vulcano Security GmbH\nlicense: All rights reserved\n",
        "license": "Proprietary, All rights reserved",
        "copyright": "Vulcano Security GmbH",
        "copyright_email": "hello@vulcanosec.com"
    },
    "mysql": {
        "id": "mysql",
        "owner": "vulcanosec",
        "name": "vulcanosec/mysql",
        "title": "Basic MySQL",
        "version": "1.0.0",
        "summary": "Verify that MySQL Server is configured securely",
        "description": "# Basic MySQL Compliance Profile\n\ncopyright: 2015, Vulcano Security GmbH\nlicense: All rights reserved\n",
        "license": "Proprietary, All rights reserved",
        "copyright": "Vulcano Security GmbH",
        "copyright_email": "hello@vulcanosec.com"
    },
    ...
}

HTTP Request

GET /owners/:owner/compliance

Return values

Parameter Type  Description
id int  profile id
owner string owner of profile
name string identifier of profile
title string human readable profile title
version string version of profile
summary string describes the purpose of the profile
description string long description
license string license of the profile
copyright string copyright holder
copyright_email string contact for copyright holder

List specific compliance profile

# lists all compliance profiles of a user
curl  "https://hostname/api/owners/vulcanosec/compliance/ssh" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

{
    "id": "ssh",
    "owner": "vulcanosec",
    "name": "vulcanosec/ssh",
    "title": "Basic SSH",
    "version": "1.0.0",
    "summary": "Verify that SSH Server and SSH Client are configured securely",
    "description": "# Basic SSH Compliance Profile\n\ncopyright: 2015, Vulcano Security GmbH\nlicense: All rights reserved\n",
    "license": "Proprietary, All rights reserved",
    "copyright": "Vulcano Security GmbH",
    "copyright_email": "hello@vulcanosec.com",
    "rules": {
        "spec/ssh_folder_spec": {
            "title": "SSH folder configuration",
            "rules": {
                "vulcanosec/ssh/basic-1": {
                    "impact": 1,
                    "title": "/etc/ssh should be a directory",
                    "desc": "In order for OpenSSH to function correctly, its configuration path must be a folder."
                },
                ...
            }
        }
    }
}

HTTP Request

GET /owners/:owner/compliance/:profile

List all compliance profiles accessible by user

The results is grouped by owners of the profiles.

# returns all profiles of a user
curl  "https://hostname/api/user/compliance" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

{
    "acme": {
        "cis-ubuntu-level1": {
            "id": "cis-ubuntu-level1",
            "owner": "admin",
            "name": "admin/cis-ubuntu-level1",
            "title": "CIS Ubuntu 14.04 LTS Server Benchmark Level 1",
            "version": "1.0.0",
            "summary": "CIS Ubuntu 14.04 LTS Server Benchmark",
            "description": "# CIS Ubuntu 14.04 LTS Server Benchmark\n\ncopyright: 2015, Vulcano Security GmbH\nlicense: All rights reserved\n",
            "license": "Proprietary, All rights reserved",
            "copyright": "Vulcano Security GmbH",
            "copyright_email": "hello@vulcanosec.com"
        }
    },
    "vulcanosec": {
        "linux": {
            "id": "linux",
            "owner": "vulcanosec",
            "name": "vulcanosec/linux",
            "title": "Basic Linux",
            "version": "1.0.0",
            "summary": "Verify that Linux nodes are configured securely",
            "description": "# Basic Linux Compliance Profile\n\ncopyright: 2015, Vulcano Security GmbH\nlicense: All rights reserved\n",
            "license": "Proprietary, All rights reserved",
            "copyright": "Vulcano Security GmbH",
            "copyright_email": "hello@vulcanosec.com"
        },
        ...
    }
}

HTTP Request

GET /user/compliance

Upload a compliance profile

This endpoint allows you to upload a tar or zip. It will extract the owner and id from the vmetadata.rb and use this information to place the profile accordingly.

# uses httpie and jq
server="https://hostname/api"
token=$(http post $server/oauth/token -a admin:flyingsheepwithwings | jq '.access_token' | tr -d '"')
tar -cvzf newprofile.tar.gz newprofile
http -a $token: "$server/owners/admin/compliance" < newprofile.tar.gz

HTTP Request

POST /owners/:owner/compliance/

Upload a compliance profile as ZIP

Uploads a new profile to a specific id via zip. Create a new tar via zip -r newprofile.zip profile_directory. You could also use the context menu of Windows and MacOS to compress the profile directory.

# uses httpie and jq
server="https://hostname/api"
token=$(http post $server/oauth/token -a admin:flyingsheepwithwings | jq '.access_token' | tr -d '"')
zip -r newprofile.zip newprofile
http -a $token: "$server/owners/admin/compliance/newprofile/zip" < newprofile.zip

HTTP Request

POST /owners/:owner/compliance/:profile/zip

Upload a compliance profile as TAR.

Upload a new profile to a specific id via tar. Create a new tar via tar -cvzf newprofile.tar.gz profile_directory

# uses httpie and jq
server="https://hostname/api"
token=$(http post $server/oauth/token -a admin:flyingsheepwithwings | jq '.access_token' | tr -d '"')
tar -cvzf newprofile.tar.gz newprofile
http -a $token: "$server/owners/admin/compliance/newprofile/tar" < newprofile.tar.gz

HTTP Request

POST /owners/:owner/compliance/:profile/tar

Download a compliance profile as TAR.

Downloads an existing profile from the server and allows you to modify it.

# uses httpie and jq
server="https://hostname/api"
token=$(http post $server/oauth/token -a admin:flyingsheepwithwings | jq '.access_token' | tr -d '"')
http -a $token: "$server/owners/admin/compliance/ssh/tar" > profile.tar.gz
tar -zxvf profile.tar.gz

HTTP Request

GET /owners/:owner/compliance/:profile/tar

Environments

List all environments

# lists all environments
curl  "https://hostname/api/owners/acme/envs" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

[
  {
    "id": "production",
    "owner": "acme",
    "name": "",
    "lastScan": "0001-01-01T00:00:00Z",
    "complianceStatus": 0,
    "patchlevelStatus": 0,
    "unknownStatus": 0
  }
]

Returns all environments in our organization

HTTP Request

GET https://hostname/api/owners/:user/envs/:env

Get environment

# lists all environments
curl  "https://hostname/api/owners/acme/envs/production" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

{
  "id": "production",
  "owner": "acme",
  "name": "",
  "lastScan": "0001-01-01T00:00:00Z",
  "complianceStatus": 0,
  "patchlevelStatus": 0,
  "unknownStatus": 0
}

HTTP Request

GET https://hostname/api/owners/:user/envs/:env/

Create environment

# creates an environment
curl -v -X POST "https://hostname/api/owners/acme/envs" \
 -H "Content-Type: application/json" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==: \
  -d "{ \"id\": \"production\"}"

It returns

Status: 204 No Content

HTTP Request

POST https://hostname/api/owners/:user/envs/

Parameter Type  Description
id string  Required. The identifier for the environment

Delete environment

# deletes an environments
curl -X DELETE "https://hostname/api/owners/acme/envs/production" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

Status: 204 No Content

HTTP Request

DELETE https://hostname/api/owners/:user/envs/:env

Errors

The VulcanoSec API uses conventional HTTP response codes to highlight a request success or failure. The following codes are used:

Error Code Meaning
200 OK – Everything worked as expected.
400 Bad Request – In most cases a required parameter is missing.
401 Unauthorized – No valid API key provided.
402  Request Failed – Parameters were valid but request failed.
403 Forbidden – You do not have the permission to execute the request
404 Not Found – The specified resource could not be found
429 Too Many Requests – You reached the rate limit.
500, 501, 502, 503 Server Error – Something went wrong.

In general, 2xx codes indicate success, 4xx indicate a request error (e.g. data is missing) and 5xx indicate an error with VulcanoSec API.

Job Runs

List all jobs

# list all jobs
curl  "https://hostname/api/owners/acme/jobs" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

[{
  "id": "76fdce4d-0734-441c-b01b-6dd6bfce081a",
  "status": "done",
  "nextRun": "2015-07-21T20:55:00Z",
  "schedule": "2015-07-21T20:55:00Z"
}, {
  "id": "c8ba8e88-7e45-4253-9081-cbb17a5f0c76",
  "status": "scheduled",
  "name": "Rec",
  "nextRun": "2015-07-21T23:11:00Z",
  "schedule": {
    "month": "*",
    "day": "21",
    "weekday": "*",
    "hour": "23",
    "minute": "11"
  }
}, {
  "id": "e0d5bbf0-a1c4-4c50-ad09-fc1486068e8c",
  "status": "skipped",
  "nextRun": "0001-01-01T00:00:00Z",
  "schedule": "2015-07-21T20:25:00Z"
}]

HTTP Request

GET https://hostname/api/owners/:user/jobs

Return values

Parameter Type  Description
id uuid id of job run
name  string name of the job
status string 'done’, 'scheduled’ or 'skipped’
nextRun iso-date  next scheduled run in UTC
schedule cron or iso-date  schedule

Get job details

# get job details
curl  "https://hostname/api/owners/acme/jobs/c8ba8e88-7e45-4253-9081-cbb17a5f0c76" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

{
  "id": "c8ba8e88-7e45-4253-9081-cbb17a5f0c76",
  "status": "scheduled",
  "name": "Rec",
  "nextRun": "2015-07-21T23:11:00Z",
  "schedule": {
    "month": "*",
    "day": "21",
    "weekday": "*",
    "hour": "23",
    "minute": "11"
  },
  "tasks": [{
    "type": "scan",
    "environments": [{
      "nodes": ["u12", "u14"],
      "id": "production"
    }],
    "compliance": [{
      "owner": "vulcanosec",
      "profile": "linux"
    }, {
      "owner": "vulcanosec",
      "profile": "ssh"
    }],
    "patchlevel": [{
      "profile": "default",
      "force": false
    }]
  }]
}

HTTP Request

GET https://hostname/api/owners/:user/jobs/:jobid

Return values

Parameter Type  Description
id uuid id of job run
name  string name of the job
status string 'done’, 'scheduled’ or 'skipped’
nextRun iso-date  next scheduled run in UTC
schedule cron or iso-date  schedule
tasks  array  contains compliance scans or patch runs

Create job

# creates a job
curl -v -X POST "https://hostname/api/owners/acme/jobs" \
 -H "Content-Type: application/json" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==: \
  -d "{\"id\":\"c8ba8e88-7e45-4253-9081-cbb17a5f0c76\",\"name\":\"Rec\",\"schedule\":{\"hour\":\"23\",\"minute\":\"11\",\"day\":\"21\",\"month\":\"*\",\"weekday\":\"*\"},\"tasks\":[{\"compliance\":[{\"owner\":\"vulcanosec\",\"profile\":\"linux\"},{\"owner\":\"vulcanosec\",\"profile\":\"ssh\"}],\"environments\":[{\"id\":\"production\",\"nodes\":[\"u12\",\"u14\"]}],\"patchlevel\":[{\"profile\":\"default\"}],\"type\":\"scan\"}]}"

uses the following json


{
  "id": "c8ba8e88-7e45-4253-9081-cbb17a5f0c76",
  "name": "Rec",
  "schedule": {
    "hour": "23",
    "minute": "11",
    "day": "21",
    "month": "*",
    "weekday": "*"
  },
  "tasks": [{
    "compliance": [{
      "owner": "vulcanosec",
      "profile": "linux"
    }, {
      "owner": "vulcanosec",
      "profile": "ssh"
    }],
    "environments": [{
      "id": "production",
      "nodes": ["u12", "u14"]
    }],
    "patchlevel": [{
      "profile": "default"
    }],
    "type": "scan"
  }]
}

``

> It returns

```http
Status: 204 No Content

HTTP Request

POST https://hostname/api/owners/:user/jobs/

Delete job

# deletes a job
curl -X DELETE "https://hostname/api/owners/acme/jobs/c8ba8e88-7e45-4253-9081-cbb17a5f0c76" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

Status: 204 No Content

HTTP Request

DELETE https://hostname/api/owners/:user/jobs/:jobid

Key Pairs

List Key Pairs

# lists key pairs for user or organization
curl  "https://hostname/api/owners/admin/keys" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

[{
    "owner": "admin",
    "id": "vagrant",
    "name": "vagrant",
    "public": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA6NF8iallvQVp22WDkTkyrtvp9eWW6A8YVr+kz4TjGYe7gHzIw+niNltGEFHzD8+v1I2YJ6oXevct1YeS0o9HZyN1Q9qgCgzUFtdOKLv6IedplqoPkcmF0aYet2PkEDo3MlTBckFXPITAMzF8dJSIFo9D8HfdOV0IAdx4O7PtixWKn5y2hMNG0zQPyUecp4pzC6kivAIhyfHilFR61RGL+GPXQ2MWZWFYbAGjyiYJnAmCP3NOTd0jMZEnDkbUvxhMmBYSdETk1rRgm+R4LOzFUGaHqHDLKLX+FIPKcF96hrucXzcWyLbIbEgE98OHlnVYCzRdK8jlqm8tehUc9c9WhQ== vagrant insecure public key"
}]

List all key pairs with public keys for an existing user or organization

HTTP Request

GET https://hostname/api/owners/:user/keys

Add Key Pair

# creates a new user
curl -X POST "https://hostname/api/owners/admin/keys/" \
 -H "Content-Type: application/json" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==: \
  -d "{ \"id\": \"vagrant\", \"name\": \"vagrant\", \"private\": \"...\", \"public\": \"...\"}"

uses the following json

{
    "name": "vagrant",
    "id": "vagrant",
    "private": "-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEA6NF8iallvQVp22WDkTkyrtvp9eWW6A8YVr+kz4TjGYe7gHzI\nw+niNltGEFHzD8+v1I2YJ6oXevct1YeS0o9HZyN1Q9qgCgzUFtdOKLv6IedplqoP\nkcmF0aYet2PkEDo3MlTBckFXPITAMzF8dJSIFo9D8HfdOV0IAdx4O7PtixWKn5y2\nhMNG0zQPyUecp4pzC6kivAIhyfHilFR61RGL+GPXQ2MWZWFYbAGjyiYJnAmCP3NO\nTd0jMZEnDkbUvxhMmBYSdETk1rRgm+R4LOzFUGaHqHDLKLX+FIPKcF96hrucXzcW\nyLbIbEgE98OHlnVYCzRdK8jlqm8tehUc9c9WhQIBIwKCAQEA4iqWPJXtzZA68mKd\nELs4jJsdyky+ewdZeNds5tjcnHU5zUYE25K+ffJED9qUWICcLZDc81TGWjHyAqD1\nBw7XpgUwFgeUJwUlzQurAv+/ySnxiwuaGJfhFM1CaQHzfXphgVml+fZUvnJUTvzf\nTK2Lg6EdbUE9TarUlBf/xPfuEhMSlIE5keb/Zz3/LUlRg8yDqz5w+QWVJ4utnKnK\niqwZN0mwpwU7YSyJhlT4YV1F3n4YjLswM5wJs2oqm0jssQu/BT0tyEXNDYBLEF4A\nsClaWuSJ2kjq7KhrrYXzagqhnSei9ODYFShJu8UWVec3Ihb5ZXlzO6vdNQ1J9Xsf\n4m+2ywKBgQD6qFxx/Rv9CNN96l/4rb14HKirC2o/orApiHmHDsURs5rUKDx0f9iP\ncXN7S1uePXuJRK/5hsubaOCx3Owd2u9gD6Oq0CsMkE4CUSiJcYrMANtx54cGH7Rk\nEjFZxK8xAv1ldELEyxrFqkbE4BKd8QOt414qjvTGyAK+OLD3M2QdCQKBgQDtx8pN\nCAxR7yhHbIWT1AH66+XWN8bXq7l3RO/ukeaci98JfkbkxURZhtxV/HHuvUhnPLdX\n3TwygPBYZFNo4pzVEhzWoTtnEtrFueKxyc3+LjZpuo+mBlQ6ORtfgkr9gBVphXZG\nYEzkCD3lVdl8L4cw9BVpKrJCs1c5taGjDgdInQKBgHm/fVvv96bJxc9x1tffXAcj\n3OVdUN0UgXNCSaf/3A/phbeBQe9xS+3mpc4r6qvx+iy69mNBeNZ0xOitIjpjBo2+\ndBEjSBwLk5q5tJqHmy/jKMJL4n9ROlx93XS+njxgibTvU6Fp9w+NOFD/HvxB3Tcz\n6+jJF85D5BNAG3DBMKBjAoGBAOAxZvgsKN+JuENXsST7F89Tck2iTcQIT8g5rwWC\nP9Vt74yboe2kDT531w8+egz7nAmRBKNM751U/95P9t88EDacDI/Z2OwnuFQHCPDF\nllYOUI+SpLJ6/vURRbHSnnn8a/XG+nzedGH5JGqEJNQsz+xT2axM0/W/CRknmGaJ\nkda/AoGANWrLCz708y7VYgAtW2Uf1DPOIYMdvo6fxIB5i9ZfISgcJ/bbCUkFrhoH\n+vq/5CIWxCPp0f85R4qxxQ5ihxJ0YDQT9Jpx4TMss4PSavPaBH3RXow5Ohe+bYoQ\nNE5OgEXk2wVfZczCZpigBKbKZHNYcelXtTt/nP3rsCuGcM4h53s=\n-----END RSA PRIVATE KEY-----",
    "public": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA6NF8iallvQVp22WDkTkyrtvp9eWW6A8YVr+kz4TjGYe7gHzIw+niNltGEFHzD8+v1I2YJ6oXevct1YeS0o9HZyN1Q9qgCgzUFtdOKLv6IedplqoPkcmF0aYet2PkEDo3MlTBckFXPITAMzF8dJSIFo9D8HfdOV0IAdx4O7PtixWKn5y2hMNG0zQPyUecp4pzC6kivAIhyfHilFR61RGL+GPXQ2MWZWFYbAGjyiYJnAmCP3NOTd0jMZEnDkbUvxhMmBYSdETk1rRgm+R4LOzFUGaHqHDLKLX+FIPKcF96hrucXzcWyLbIbEgE98OHlnVYCzRdK8jlqm8tehUc9c9WhQ== vagrant insecure public key"
}

It returns

Status: 204 No Content

Adds a new keypair to an existing user or organization

HTTP Request

POST https://hostname/api/owners/:user/keys

Parameter Type  Description
id string identifier of key
name string user readable name of the key
public string public key in openssh format
private string private key in openssh format

Edit Key Pair

# edit a key pair
curl -X PATCH "https://hostname/api/owners/admin/keys/vagrant" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==: \
 -d "{\"name\":\"My Vagrant Key\"}"

It returns

Status: 204 No Content

Edits an existing key pair from a user or organization

HTTP Request

PATCH https://hostname/api/owners/:user/keys/:keyname

Delete Key Pair

# deletes a key pair
curl -X DELETE "https://hostname/api/owners/admin/keys/vagrant" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

Status: 204 No Content

Removes an existing key pair from a user or organization

HTTP Request

DELETE https://hostname/api/owners/:user/keys/:keyname

Nodes

Get environments nodes

# lists all nodes in environment
curl  "https://hostname/api/owners/acme/envs/production/nodes" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

[
  {
    "id": "192.168.100.200",
    "environment": "production",
    "owner": "acme",
    "name": "",
    "hostname": "192.168.100.200",
    "loginMethod": "ssh",
    "loginUser": "root",
    "loginPassword": "",
    "loginKey": "sshpublickey",
    "loginPort": 0,
    "disableSudo": false,
    "sudoOptions": "",
    "sudoPassword": "",
    "lastScan": "0001-01-01T00:00:00Z",
    "lastScanID": "",
    "os_family": "",
    "os_release": "",
    "os_arch": "",
    "complianceStatus": 0,
    "patchlevelStatus": 0,
    "unknownStatus": 0
  }
]

HTTP Request

GET https://hostname/api/owners/:user/envs/:env/nodes

Get specific nodes

# get node overview
curl  "https://hostname/api/owners/acme/envs/production/nodes/192.168.100.200" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

{
  "id": "192.168.100.200",
  "environment": "production",
  "owner": "acme",
  "name": "",
  "hostname": "192.168.100.200",
  "loginMethod": "ssh",
  "loginUser": "root",
  "loginPassword": "",
  "loginKey": "sshpublickey",
  "loginPort": 0,
  "disableSudo": false,
  "sudoOptions": "",
  "sudoPassword": "",
  "lastScan": "0001-01-01T00:00:00Z",
  "lastScanID": "",
  "os_family": "",
  "os_release": "",
  "os_arch": "",
  "complianceStatus": 0,
  "patchlevelStatus": 0,
  "unknownStatus": 0
}

HTTP Request

GET https://hostname/api/owners/:user/envs/:env/nodes/:node

Create node

# creates a node
curl -X POST "https://hostname/api/owners/acme/envs/nodes" \
 -H "Content-Type: application/json" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==: \
  -d "{\"loginUser\":\"root\",\"loginMethod\":\"ssh\",\"loginKey\":\"acme/nameofkey\",\"hostname\":\"192.168.100.200\",\"loginPort\":22,\"id\":\"192.168.100.200\"}"

uses the following json

{
    "loginUser": "root",
    "loginMethod": "ssh",
    "loginKey": "acme/nameofkey",
    "hostname": "192.168.100.200",
    "loginPort": 22,
    "id": "192.168.100.200"
}

It returns

Status: 204 No Content

HTTP Request

POST https://hostname/api/owners/:user/envs/:env/nodes

Get node status

# shows node status
curl  "https://hostname/api/owners/acme/envs/production/nodes" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

[
    {
        "complianceStatus": 0, 
        "disableSudo": false, 
        "environment": "production", 
        "hostname": "192.168.100.200", 
        "id": "192.168.100.200", 
        "lastScan": "2015-06-26T15:17:30.945183863Z", 
        "lastScanID": "1170660a-7e50-4c3a-6da7-eaa510e2f0a9", 
        "loginKey": "admin/vagrant", 
        "loginMethod": "ssh", 
        "loginPassword": "", 
        "loginPort": 22, 
        "loginUser": "root", 
        "name": "", 
        "os_arch": "x86_64", 
        "os_family": "ubuntu", 
        "os_release": "14.04", 
        "owner": "admin", 
        "patchlevelStatus": 0.045643155, 
        "sudoOptions": "", 
        "sudoPassword": "", 
        "unknownStatus": 0
    }
]

HTTP Request

GET https://hostname/api/owners/:user/envs/:env/nodes/:node

Connectivity check for node

# shows node patch state
curl  "https://hostname/api/owners/acme/envs/production/nodes/192.168.100.200/connectivity" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

Status: 200 (success) or 402 (error)

HTTP Request

GET https://hostname/api/owners/:user/envs/:env/nodes/:node/connectivity

Response Code Meaning
200 OK – Everything worked as expected.
402  Request Failed – Node is not reachable.

In case of an error the request returns one of the following error messages:

Connection Timeout

{
  "error":"connection timed out",
  "message":"Failed to connect to {destination}, connection timed out."
}

Connection Refused

{
  "error":"connection refused",
  "message":"Failed to connect to {destination}, connection refused."
}

Authentication Failed

{
  "error":"authentication failed",
  "message":"Authentication failed for {destination}"
}

Sudo Password Required

{
  "error":"sudo password required",
  "message":"Failed to run commands on {destination}: "+
  "The node is configured to use sudo, but sudo requires a password to run commands."
}

Wrong Sudo Password

{
  "error":"wrong sudo password",
  "message":"Failed to run commands on {destination}: Sudo password is incorrect."
}

Cannot Use Sudo

{
  "error":"no sudo",
  "message":"Failed to run commands on {destination}: "+
  "Cannot use sudo, please deactivate it or configure sudo for this user."
}

Get compliance level of node

# shows node compliance state
curl  "https://hostname/api/owners/acme/envs/production/nodes/192.168.100.200/compliance" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

[
    {
        "failures": 1, 
        "impact": 1, 
        "log": "Linux kernel parameter \"net.ipv4.tcp_syncookies\" value should eq 1", 
        "profileID": "linux", 
        "profileOwner": "vulcanosec", 
        "rule": "vulcanosec/linux/sysctl-ipv4-9.2", 
        "skipped": false
    }, 
    {
        "failures": 1, 
        "impact": 0.5, 
        "log": "Path \"/tmp\" should be mounted", 
        "profileID": "linux", 
        "profileOwner": "vulcanosec", 
        "rule": "vulcanosec/linux/fs-1", 
        "skipped": false
    }, 
...
]

HTTP Request

GET https://hostname/api/owners/:user/envs/:env/nodes/:node/compliance

Get available patches for node

# shows node patch state
curl  "https://hostname/api/owners/acme/envs/production/nodes/192.168.100.200/patches" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

[
    {
        "arch": "amd64",
        "criticality": 0,
        "installedVersion": "2.7.3-0ubuntu3.6",
        "name": "python2.7-minimal",
        "repo": "Ubuntu:12.04/precise-updates",
        "type": "deb",
        "version": "2.7.3-0ubuntu3.8"
    },
...
]

HTTP Request

GET https://hostname/api/owners/:user/envs/:env/nodes/:node/patches

Get installed packages of node

# shows node patch state
curl  "https://hostname/api/owners/acme/envs/production/nodes/192.168.100.200/packages" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

[
    {
        "arch": "add",
        "name": "adduser",
        "repo": "",
        "type": "deb",
        "version": "3.113ubuntu2"
    },
    {
        "arch": "commandline",
        "name": "apt",
        "repo": "",
        "type": "deb",
        "version": "0.8.16~exp12ubuntu10.24"
    },
...
]

HTTP Request

GET https://hostname/api/owners/:user/envs/:env/nodes/:node/packages

Organizations

List your organizations

# lists all organizations
curl  "https://hostname/api/orgs" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

[
  {
    "id": "acme",
    "name": "Acme Industries"
  }
]

Returns a list of all your organizations.

HTTP Request

GET https://hostname/api/orgs/

Get an organization

# Get an organizations
curl  "https://hostname/api/orgs/acme" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

{
  "id": "acme",
  "name": "Acme Industries"
}

HTTP Request

GET https://hostname/api/orgs/:org

Return a single organization.

Create an organization

# creates a new organizations
curl -X POST "https://hostname/api/orgs" \
 -H "Content-Type: application/json" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==: \
  -d "{ \"id\":\"acme\", \"name\":\"Acme Industries\"}"

It returns

Status: 204 No Content

HTTP Request

POST https://hostname/api/orgs/

Arguments

Parameter Type  Description
id string  Required. The ID of the organization
name string  Required. The name of the organization

Edit an organization

# edits an organizations
curl -X PATCH "https://hostname/api/orgs/acme" \
 -H "Content-Type: application/json" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==: \
  -d "{\"name\":\"Acme Industries Inc.\"}"

It returns

Status: 204 No Content

Edits the name of an organization.

HTTP Request

PATCH https://hostname/api/orgs/

Arguments

Parameter Type  Description
name string  The name of the organization

Delete an organization

# deletes an organizations
curl -X DELETE "https://hostname/api/orgs/acme" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

Status: 204 No Content

This request deletes an existing organization. Deleting an organization requires admin rights access.

HTTP Request

DELETE https://hostname/api/orgs/:org

Patch Runs

List all patchrun reports

# list all scans
curl  "https://hostname/api/owners/acme/patchruns" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

[
  {
    "config": null,
    "end": "2015-06-29T04:52:00.739010716Z",
    "failureCount": 0,
    "id": "210a994c-8bef-4c89-4a1c-09418e19d92c",
    "nodeCount": 1,
    "owner": "acme",
    "progress": 0,
    "skipCount": 0,
    "start": "2015-06-29T04:51:39.739010716Z",
    "successCount": 1
  }
]

HTTP Request

GET https://hostname/api/owners/:user/patchruns

Return values

Parameter Type  Description
id string id of patch run
start date  iso time
end date  iso time
nodeCount int  amount of applied nodes
successCount int  amount of successful patches
failureCount int  amount of patches with errors
skipCount int amount patches that have not been applied

Get patch run details

# get scan details
curl  "https://hostname/api/owners/acme/patchruns/210a994c-8bef-4c89-4a1c-09418e19d92c" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

{
    "config": null,
    "end": "0001-01-01T00:00:00Z",
    "failureCount": 0,
    "id": "210a994c-8bef-4c89-4a1c-09418e19d92c",
    "nodeCount": 1,
    "owner": "admin",
    "progress": 0,
    "skipCount": 0,
    "start": "2015-06-29T04:51:39.739010716Z",
    "successCount": 1
}

HTTP Request

GET https://hostname/api/owners/:user/patchruns/:patchrunid

List nodes of patch run

# get scan details
curl  "https://hostname/api/owners/acme/patchruns/210a994c-8bef-4c89-4a1c-09418e19d92c/nodes" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

[
    {
        "environment": "production",
        "log": "",
        "node": "u14",
        "packageCount": 1,
        "patchRunID": "210a994c-8bef-4c89-4a1c-09418e19d92c",
        "successRate": 1
    }
]

HTTP Request

GET https://hostname/api/owners/:user/patchruns/:patchrunid/nodes

Execute a patch run


curl -X POST "https://hostname/api/owners/acme/patchrun" \
 -H "Content-Type: application/json" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==: \
 -d "{\"environments\":[{\"nodes\":[\"u14\"],\"id\":\"production\"}],\"packages\":[{\"name\":\"initscripts\",\"version\":\"2.88dsf-41ubuntu6.2\",\"type\":\"deb\"}]}"

The json request looks as follows

{
    "environments":[{
        "nodes":["u14"],
        "id":"production"
    }],
    "packages":[{
        "name":"initscripts",
        "version":"2.88dsf-41ubuntu6.2",
        "type":"deb"
    }]
}

It returns

{
    "id": "e896505a-ebdd-4a76-621a-b3a5108f811e"
}

HTTP Request

POST https://hostname/api/owners/:user/patchrun

Arguments

Parameter Type  Description
environments array  list of environments and selected nodes
packages array  list of packages that should be updated

Return values

Parameter Type  Description
id string patchrun identifier

Scans

List all scans reports

# list all scans
curl  "https://hostname/api/owners/acme/scans" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

[
  {
    "id": "a74566b9-b527-437f-480f-e56c5b8a1791",
    "owner": "acme",
    "start": "2015-05-22T01:10:37.133367688Z",
    "end": "2015-05-22T01:10:42.491573741Z",
    "nodeCount": 1,
    "complianceProfiles": 1,
    "patchlevelProfiles": 1,
    "complianceStatus": 0,
    "patchlevelStatus": 0,
    "unknownStatus": 0
  }
]

HTTP Request

GET https://hostname/api/owners/:user/scans

Get scan details

# get scan details
curl  "https://hostname/api/owners/acme/scans/90def607-1688-40f5-5a4c-161c51fd8aac" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

{
  "id": "a74566b9-b527-437f-480f-e56c5b8a1791",
  "owner": "admin",
  "start": "2015-05-22T01:10:37.133367688Z",
  "end": "2015-05-22T01:10:42.491573741Z",
  "nodeCount": 1,
  "complianceProfiles": 1,
  "patchlevelProfiles": 1,
  "complianceStatus": 0,
  "patchlevelStatus": 0,
  "unknownStatus": 0,
  "complianceSummary": {
    "success": 0,
    "minor": 0,
    "major": 43,
    "critical": 2,
    "skipped": 0,
    "total": 45
  },
  "patchlevelSummary": {
    "success": 0,
    "minor": 0,
    "major": 0,
    "critical": 0,
    "unknown": 0,
    "total": 0
  }
}

HTTP Request

GET https://hostname/api/owners/:user/scans/:scanid

Parameter Type  Description
id string scan id
owner string scan owner
start iso date scan start
end iso date scan end
nodeCount  int amount of tested nodes
success float amount of successful rules
critical float amount of failed rules
major float amount of rules with major errors
minor float amount of rules with minor errors
skipped float amount of nodes with skipped rules

Get executed compliance rules for scan

# shows executed compliance rules for scan
curl  "https://hostname/api/owners/acme/scans/90def607-1688-40f5-5a4c-161c51fd8aac/rules" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

{
  "vulcanosec": {
    "linux": {
      "vulcanosec/linux/basic-1": {
        "log": "",
        "complianceStatus": 1,
        "unknownStatus": 0
      },
      "vulcanosec/linux/fs-1": {
        "log": "",
        "complianceStatus": 0.5,
        "unknownStatus": 0
      },
...

HTTP Request

GET https://hostname/api/owners/:user/scans/:scanid/rules

Return values

Parameter Type  Description
log string  rule description
complianceStatus int CVSS range

Get nodes for scan

# scanned nodes
curl  "https://hostname/api/owners/acme/scans/90def607-1688-40f5-5a4c-161c51fd8aac/nodes" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

[
  {
    "environment": "production",
    "node": "192.168.59.107:11024",
    "complianceStatus": 0,
    "patchlevelStatus": -1,
    "unknownStatus": 0,
    "os_family": "",
    "os_release": "",
    "os_arch": "",
    "complianceSummary": {
      "success": 0,
      "minor": 0,
      "major": 43,
      "critical": 2,
      "skipped": 0,
      "total": 45
    },
    "patchlevelSummary": {
      "success": 0,
      "minor": 0,
      "major": 0,
      "critical": 0,
      "unknown": 0,
      "total": 0
    },
    "patchStatus": null
  }
]

HTTP Request

GET https://hostname/api/owners/:user/scans/:scanid/nodes

Get compliance results for each node

# compliance rules results
curl  "https://hostname/api/owners/acme/scans/90def607-1688-40f5-5a4c-161c51fd8aac/envs/production/nodes/192.168.100.200/compliance" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

[
  {
    "profileOwner": "vulcanosec",
    "profileID": "linux",
    "rule": "vulcanosec/linux/basic-1",
    "impact": 1,
    "failures": 1,
    "skipped": false,
    "log": "Path \"/etc/ssh\" should be directory"
  },
  ...
]

HTTP Request

GET https://hostname/api/owners/:user/scans/:scanid/envs/:env/nodes/:node/compliance

Return values

Parameter Type  Description
rule string rule identifier
impact float  value between 0 and 1
failures int -1=skipped, 0=no failure, 1+ amount of failures per rule
log string  error log
profileOwner string  owner of compliance rules
profileID string compliance rules identifier

Get available patches for each node

curl  "https://hostname/api/owners/acme/scans/90def607-1688-40f5-5a4c-161c51fd8aac/envs/production/nodes/192.168.100.200/patches" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

[
    {
        "arch": "amd64", 
        "criticality": 0, 
        "installedVersion": "2.7.3-0ubuntu3.6", 
        "name": "python2.7-minimal", 
        "repo": "Ubuntu:12.04/precise-updates", 
        "type": "deb", 
        "version": "2.7.3-0ubuntu3.8"
    }
    ...
]

HTTP Request

GET https://hostname/api/owners/:user/scans/:scanid/envs/:env/nodes/:node/patches

Return values

Parameter Type  Description
criticality integer  0-10 CVSS score
name string  package name
version string  package version
arch string  cpu architecture
repo string  package repository

Get installed packages for each node

curl  "https://hostname/api/owners/acme/scans/90def607-1688-40f5-5a4c-161c51fd8aac/envs/production/nodes/192.168.100.200/packages" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

[
    {
        "arch": "add", 
        "name": "adduser", 
        "repo": "", 
        "type": "deb", 
        "version": "3.113ubuntu2"
    }, 
    {
        "arch": "commandline", 
        "name": "apt", 
        "repo": "", 
        "type": "deb", 
        "version": "0.8.16~exp12ubuntu10.24"
    }, 
    ...
]

HTTP Request

GET https://hostname/api/owners/:user/scans/:scanid/envs/:env/nodes/:node/packages

Execute a new scan


curl -X POST "https://hostname/api/owners/acme/scans" \
 -H "Content-Type: application/json" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==: \
  -d "{\"compliance\":[{\"owner\":\"vulcanosec\",\"profile\":\"linux\"},{\"owner\":\"vulcanosec\",\"profile\":\"ssh\"}],\"environments\":[{\"id\":\"production\",\"nodes\":[\"192.168.100.200\"]}],\"patchlevel\":[{\"profile\":\"default\"}]"

The json request looks as follows

{
    "compliance": [{
        "owner": "vulcanosec",
        "profile": "linux"
    }, {
        "owner": "vulcanosec",
        "profile": "ssh"
    }],
    "environments": [{
        "id": "production",
        "nodes": ["192.168.100.200"]
    }],
    "patchlevel": [{
        "profile" : "default"
    }]
}

It returns

{
  "id" : "57130678-1a1f-405d-70bf-fe570a25621e"
}

HTTP Request

POST https://hostname/api/owners/:user/scans

Arguments

Parameter Type  Description
compliance array  list of selected profiles
environments array  list of environments and selected nodes
patchlevel array  patch level scan profile

Return values

Parameter Type  Description
id string  scan identifier

Server configuration

Some server parameters are exposed via API and can be configured.

Get server configuration

# get the server's configuration
curl -X GET "https://hostname/api/server/config" \
 -H "Content-Type: application/json" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

{
    "detectTimeout":25,
    "scanTimeout":1800,
    "updateTimeout":1800
}

This returns the server’s global configuration, which can be edited via API or configuration file. It only contains parameters that can be safely exposed.

All timeout configurations are set in seconds, i.e. 1800 results in a 30min timeout.

Edit server configuration

# edits the server's global configuration
curl -X PATCH "https://hostname/api/server/config" \
 -H "Content-Type: application/json" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==: \
 -d "{\"detectTimeout\":10, \"scanTimeout\": 1500}"

It returns

Status: 204 No Content

Teams

List teams

# list teams
curl  "https://hostname/api/orgs/acme/teams" \
  -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

The above command returns JSON structured like this:

[
  {
    "id": "owners",
    "org": "acme",
    "name": "Owners"
  }
]

This request returns all teams that are part of an organization. By default, each organization has a owners team.

HTTP Request

GET https://hostname/api/orgs/:org/teams

Get team

# get a team
curl  "https://hostname/api/orgs/acme/teams/owners" \
  -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

The above command returns JSON structured like this:

{
  "id": "owners",
  "org": "acme",
  "name": "Owners",
  "members": [
    "admin"
  ],
  "permissions": {
    "harden": "true",
    "manage": "true",
    "patch": "true",
    "scan": "true"
  }
}

Get detailed information about one team.

HTTP Request

GET https://hostname/api/orgs/:org/teams/:team

Create team

# creates a new team
curl -X POST "https://hostname/api/orgs/acme/teams" \
 -H "Content-Type: application/json" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==: \
  -d "{ \"id\": \"audit\", \"name\": \"Auditors\", \"permissions\": {\"scan\": \"true\"}}"

It returns

Status: 204 No Content

Create a new team within your organization.

HTTP Request

POST https://hostname/api/orgs/:org/teams

Arguments

Parameter Type  Description
id string  Required. The ID of the team
name string  Required. The name of the team
permissions object Optional. Sets the team permissions

The permissions are defined as follows:

{
    id: 'audit',
    name: 'Auditors',
    permissions: {
        scan: "true"
    }
}

VulcanoSec supports the following permissions: manage, scan, harden and patch.

Edit team

# edit team
curl -X PATCH "https://hostname/api/orgs/acme/teams/audit" \
 -H "Content-Type: application/json" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==: \
  -d "{\"name\":\"External Auditors\"}"

It returns

Status: 204 No Content

Create a new team within your organization.

HTTP Request

PATCH https://hostname/api/orgs/:org/teams/:team

Arguments

Parameter Type  Description
name string Optional. The name of the team
permissions object Optional. Sets the team permissions

Delete team

# deletes a team
curl -X DELETE "https://hostname/api/orgs/acme/teams/audit" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

Status: 204 No Content

Deletes a team within your organization.

HTTP Request

DELETE https://hostname/api/orgs/:org/teams/:team

Edit Team Permissions

# edit team
curl -X PATCH "https://hostname/api/orgs/acme/teams/audit" \
 -H "Content-Type: application/json" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==: \
  -d "{\"permissions\":{\"manage\":\"false\"}}"

It returns

Status: 204 No Content

HTTP Request

PATCH https://hostname/api/orgs/:org/teams/:team/members/:member

List team memberships

# list teams
curl "https://hostname/api/orgs/acme/teams/owners" \
  -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

The above command returns JSON structured like this:

{
  "id": "owners",
  "org": "acme",
  "name": "Owners",
  "members": [
    "admin"
  ],
  "permissions": {
    "harden": "true",
    "manage": "true",
    "patch": "true",
    "scan": "true"
  }
}

HTTP Request

GET https://hostname/api/orgs/:org/teams/:team/members

Add team membership

# add a team member
curl -X POST "https://hostname/api/orgs/acme/teams/owners/members" \
 -H "Content-Type: application/json" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==: \
  -d "[\"bob\"]"

It returns

Status: 204 No Content

HTTP Request

POST https://hostname/api/orgs/:org/teams/:team/members

Parameter Type  Description
users array  Required. Array of user ids

Remove team membership

# delete a team member
curl -X DELETE "https://hostname/api/orgs/acme/teams/audit/members/bob" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

Status: 204 No Content

HTTP Request

DELETE https://hostname/api/orgs/:org/teams/:team/members/:member

Users

Get all users

# lists all users
curl  "https://hostname/api/users" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

[
  {
    "id": "admin",
    "name": "Core Admin"
  }
]

List all users in your tenant.

HTTP Request

GET https://hostname/api/users

Get a single user

# lists all users
curl  "https://hostname/api/users/admin" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

{
  "id": "admin",
  "name": "Core Admin",
  "preferences": null,
  "permissions": {
    "site_admin": "true"
  }
}

Returns a specific user in your tenant.

HTTP Request

GET https://hostname/api/users/:user

Create a new user

# creates a new user
curl -X POST "https://hostname/api/users" \
 -H "Content-Type: application/json" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==: \
  -d "{ \"id\": \"bob\", \"name\": \"BoB\", \"pass\": \"helloworld\"}"

It returns

Status: 204 No Content

Creates a new user in your tenant.

HTTP Request

POST https://hostname/api/users/

Parameter Type  Description
id string  Required. The ID of the user
name string  Required. The name of the user
password string  Required. Unencrypted password 
{
  id: 'bob',
  name: 'Bob Barrel',
  password : 'mysecretpassword'
}

Edit user

# edit team
curl -X PATCH "https://hostname/api/users/bob" \
 -H "Content-Type: application/json" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==: \
  -d "{\"name\":\"Bob Maier\"}"

It returns

Status: 204 No Content

Edit an existing user.

HTTP Request

PATCH https://hostname/api/users/:user

Parameter Type  Description
name string Optional. The name of the user
pass string Optional. Unencrypted password

Delete user

# deletes a user
curl -X DELETE "https://hostname/api/users/bob" \
 -u VS3x1XSg4Hk/wxw8IP+2XpmoKynR7urxglaGfLfFRXbxYljxNW5mksOSNj+BkO2DVoQehGosBnqCJA8WAz3Jyg==:

It returns

Status: 204 No Content

Deletes an existing user.

HTTP Request

DELETE https://hostname/api/users/:user