amigo: a google cloud platform security toolkit

tl; dr

• amigo uses the GCP API to fetch an organization's project data and, with a set of customizable rules, searches for security risks
• this is how it works:
  • i) amigo retrieves the GCP project list and their attributes (defined in a config.yaml file)
  • ii) for each attribute in a project, amigo creates an updated report
  • iii) amigo checks the previous report for differences (verifying when the data was modified), if there is a diff, amigo logs the report for this diff
  • iv) amigo saves the data in a database and then it checks the custom rules specified in rules.yaml, reporting everything that violates those rules
  • v) the science generated by amigo can be fed into ELK

---

running amigo

• set a venv and install:

make venv
source venv/bin/activate
make install

• create a service account (this should be done once, the first time you run amigo):

  • 1. create a project and a service account at https://console.cloud.google.com/iam-admin/serviceaccounts
  • 2. add the IAM roles security reviewer and viewer permissions to the service account
  • 3. download the service account JSON credential file to a safe directory (e.g. your home directory). if amigo runs in other machines (or other people in the same organization are running amigo), this key can be shared (and step 1. and 2. do not need to be repeated)

• install the gcloud SDK and authenticate with:

gcloud auth application-default login

• check whether env variable GOOGLE_APPLICATION_CREDENTIALS is pointing to the service account JSON credential file

• copy config.yaml_example to config.yaml. in the bottom of this file you are able to edit the attributes that you want to report on:

• Attributes to inspect:

gcp_attributes:
    compute:
        - firewalls
        - networks
        - snapshots

• inspect rules.yaml either removing or adding rules that should be searched in the reports

• finnaly, run amigo with:

sudo amigo

• this will retrieve the data from GCP and generate JSON reports (saved in the variable reports_dir in the config file). it is advised to watch for STERR and STDOUT in the log_file file defined in config.yaml (default to amigo_log.txt):

tail -f amigo_log.txt

---

alerting with amigo

• relevant reports (e.g. diff reports) are generated inside the directory defined as results_dir, in the file results.log (e.g. /log/amigo.log). this is a JSON file that can be fed to ELK

---

creating custom rules

• firewall reports have this format:

{
  "kind": "compute#firewall",
  "network": "https://www.googleapis.com/compute/v1/projects/<name>/global/networks/default",
  "direction": "INGRESS",
  "sourceRanges": [
    "0.0.0.0/0"
  ],
  "name": "default-allow-icmp",
  "priority": 65534,
  "allowed": [
    {
      "IPProtocol": "icmp"
    }
  ],
  "creationTimestamp": <Time stamp>,
  "id": <ID>,
  "selfLink": "https://www.googleapis.com/compute/v1/projects/<name>/global/firewalls/default-allow-icmp",
  "description": "Allow ICMP from anywhere"
}

• networks snapshot reports have this format:

{
  "kind": "compute#network",
  "description": "Default network for the project",
  "subnetworks": [
    "https://www.googleapis.com/compute/v1/projects/<name>/regions/<region>/subnetworks/default",
  ],
  "autoCreateSubnetworks": true,
  "routingConfig": {
    "routingMode": "REGIONAL"
  },
  "creationTimestamp": <Time stamp>,
  "id": <ID>,
  "selfLink": "https://www.googleapis.com/compute/v1/projects/<name>/global/networks/default",
  "name": "default"
}

• snapshot reports have this format:

{
  "status": "READY",
  "kind": "compute#snapshot",
  "storageBytes": <number>,
  "name": <name>,
  "sourceDisk": "https://www.googleapis.com/compute/v1/projects/<name>/zones/us-central1-c/disks/deployhost",
  "storageBytesStatus": "UP_TO_DATE",
  "labelFingerprint": <code>,
  "sourceDiskId": <ID>,
  "diskSizeGb": <size>,
  "licenses": [
    "https://www.googleapis.com/compute/v1/projects/centos-cloud/global/licenses/centos-7"
  ],
  "creationTimestamp": <time stamp>,
  "id": <ID>,
  "selfLink": "https://www.googleapis.com/compute/v1/projects/<name>/global/snapshots/snapshot-1-deployhost"
}

• instance template reports have this format:

{
  "kind": "compute#instanceTemplate",
  "description": "",
  "properties": {
    "machineType": <type>,
    "tags": {
      "items": [
        <items>
      ]
    },
    "disks": [
      {
        "deviceName": "persistent-disk-0",
        "kind": "compute#attachedDisk",
        "initializeParams": {
          "sourceImage": "global/images/<name>",
          "diskType": "pd-standard"
        },
        "autoDelete": true,
        "index": 0,
        "boot": true,
        "mode": "READ_WRITE",
        "interface": "SCSI",
        "type": "PERSISTENT"
      }
    ],
    "scheduling": {
      "automaticRestart": true,
      "preemptible": false,
      "onHostMaintenance": "MIGRATE"
    },
    "serviceAccounts": [
      {
        "scopes": [
          "https://www.googleapis.com/auth/compute.readonly"
        ],
        "email": <service-account-email>
      }
    ],
    "metadata": {
      "items": [
        <metadata>
      "kind": "compute#metadata",
    }
  },
  "creationTimestamp": "2017-11-14T12:24:00.744-08:00",
  "id": <ID>
  "selfLink": "https://www.googleapis.com/compute/v1/projects/<project-name>/global/instanceTemplates/",
  "name": <name>
}