Automatically Sync Schemas with GitHub Actions

info

The English user guide is currently in beta preview. Most of the documents have been automatically translated from the Japanese version. Should you find any inaccuracies, please reach out to Flatt Security.

info

This feature is available only to organizations that have subscribed to our Web Application Security Assessment.

This document explains how to automatically sync schemas with Shisho Cloud using GitHub Actions.

Set up GitHub Actions to Log in to Shisho Cloud

To allow your GitHub Actions workflow to log in to Shisho Cloud, you need to configure a few things in Shisho Cloud. First, go to the Bot creation page in Shisho Cloud and create a new Bot. A bot is an entity that has permission to access Shisho Cloud organizations. Your GitHub Actions job will log in to Shisho Cloud as this bot.

Once you have created a bot, click on the bot name to go to the Trust Condition setting screen.

A trust condition is a condition that a GitHub Actions job must meet in order to log in to Shisho Cloud as that bot. Enter the Organization and repository name of the GitHub repository where your workflow is stored. This will allow GitHub Actions jobs belonging to that repository to log in to Shisho Cloud as the bot you just created. Once you have entered the information, click the "Save" button.

Basic GitHub Actions

A GitHub Actions workflow for automatic synchronization will look like this:

name: "Sync the schema with Shisho Cloud"

permissions:
  contents: read
  id-token: write # Required to allow the workflow to log in to Shisho Cloud

on:
  push:
    # Trigger when pushed to the main branch
    branches:
      - main
    # Detect only changes in the schema file
    paths:
      # FIXME: Replace with the path to the YAML file where this workflow is defined
      - .github/workflows/sync.yaml
      # FIXME: Replace with the path to the schema file you want to reference
      - docs/openapi.yaml

jobs:
  sync:
    name: Sync
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install shishoctl
        run: |
          SHISHOCTL_URL="https://shisho.dev/releases/shishoctl-0.12.0-x86_64-unknown-linux-gnu"
          sudo curl -L $SHISHOCTL_URL -o /usr/local/bin/shishoctl
          sudo chmod +x /usr/local/bin/shishoctl

      - name: Sign in
        uses: flatt-security/shisho-cloud-action@v1
        with:
          # FIXME: The bot-id to be entered is described in the Trust Condition setting screen
          bot-id: "BTXXXXXXXXXXXXXXXXXXXXXXXXXX"

      # Upload the schema to Shisho Cloud using shishoctl
      - name: Sync with Shisho Cloud
        run: |
          shishoctl web-application collect-endpoints openapi \
            --org $ORG_ID \
            --app $APP_ID \
            --path $SCHEMA_PATH
        env:
          ORG_ID: ${{ vars.SHISHO_CLOUD_ORG_ID }}
          APP_ID: ${{ vars.SHISHO_CLOUD_APP_ID }}
          # FIXME: Replace with the path to the schema file you want to reference
          SCHEMA_PATH: docs/openapi.yaml

Be sure to replace any occurrences of FIXME with the appropriate values.

Also, register the following variables in your GitHub repository. See the GitHub official documentation for details on how to set them up.

• SHISHO_CLOUD_ORG_ID Organization ID
  • Included in the URL of the Shisho Cloud dashboard
  • https://cloud.shisho.dev/{{ Organization ID }}/dashboard
• SHISHO_CLOUD_APP_ID Application ID
  • Included in the URL of the application page
  • https://cloud.shisho.dev/{{ Organization ID }}/applications/{{ Application ID }}

Integration with OpenAPI Specification

name: "Sync the OpenAPI Specification with Shisho Cloud"

permissions:
  contents: read
  id-token: write # Required to allow the workflow to log in to Shisho Cloud

on:
  push:
    branches:
      - main
    paths:
      # Path to the workflow file
      - .github/workflows/sync-openapi.yaml
      # FIXME: Replace with the path to the schema file you want to reference
      - docs/openapi.yaml

jobs:
  sync:
    name: Sync
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install shishoctl
        run: |
          SHISHOCTL_URL="https://shisho.dev/releases/shishoctl-0.12.0-x86_64-unknown-linux-gnu"
          sudo curl -L $SHISHOCTL_URL -o /usr/local/bin/shishoctl
          sudo chmod +x /usr/local/bin/shishoctl

      - name: Sign in
        uses: flatt-security/shisho-cloud-action@v1
        with:
          # FIXME: The bot-id to be entered is described in the Trust Condition setting screen
          bot-id: "BTXXXXXXXXXXXXXXXXXXXXXXXXXX"

      - name: Sync with Shisho Cloud
        run: |
          shishoctl web-application collect-endpoints openapi \
            --org $ORG_ID \
            --app $APP_ID \
            --path $SCHEMA_PATH
        env:
          ORG_ID: ${{ vars.SHISHO_CLOUD_ORG_ID }}
          APP_ID: ${{ vars.SHISHO_CLOUD_APP_ID }}
          # FIXME: Replace with the path to the schema file you want to reference
          SCHEMA_PATH: docs/openapi.yaml

Integration with GraphQL Schema

name: "Sync the GraphQL Schema with Shisho Cloud"

permissions:
  contents: read
  id-token: write # Required to allow the workflow to log in to Shisho Cloud

on:
  push:
    branches:
      - main
    paths:
      # Path to the workflow file
      - .github/workflows/sync-graphql.yaml
      # FIXME: Replace with the path to the schema file you want to reference
      - docs/schema.graphql

jobs:
  sync:
    name: Sync
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install shishoctl
        run: |
          SHISHOCTL_URL="https://shisho.dev/releases/shishoctl-0.12.0-x86_64-unknown-linux-gnu"
          sudo curl -L $SHISHOCTL_URL -o /usr/local/bin/shishoctl
          sudo chmod +x /usr/local/bin/shishoctl

      - name: Sign in
        uses: flatt-security/shisho-cloud-action@v1
        with:
          # FIXME: The bot-id to be entered is described in the Trust Condition setting screen
          bot-id: "BTXXXXXXXXXXXXXXXXXXXXXXXXXX"

      - name: Sync with Shisho Cloud
        run: |
          shishoctl web-application collect-endpoints graphql \
            --org $ORG_ID \
            --app $APP_ID \
            --max-depth 5 \
            --url $ENDPOINT_URL \
            --path $SCHEMA_PATH
        env:
          ORG_ID: ${{ vars.SHISHO_CLOUD_ORG_ID }}
          APP_ID: ${{ vars.SHISHO_CLOUD_APP_ID }}
          ENDPOINT_URL: ${{ vars.SHISHO_CLOUD_GRAPHQL_ENDPOINT_URL }}
          # FIXME: Replace with the path to the schema file you want to reference
          SCHEMA_PATH: docs/schema.graphql

You need to register the following variable to GitHub in addition to the basic settings.

• SHISHO_CLOUD_GRAPHQL_ENDPOINT_URL GraphQL endpoint URL to be used for scanning.

Integration with Connect RPC (Protocol Buffers)

name: "Sync the Connect RPC (Protocol Buffers) with Shisho Cloud"

permissions:
  contents: read
  id-token: write # Required to allow the workflow to log in to Shisho Cloud

on:
  push:
    branches:
      - main
    paths:
      # Path to the workflow file
      - .github/workflows/sync-connectrpc.yaml
      # FIXME: Replace with the path to the folder containing the schema file you want to reference
      - docs/proto/**

jobs:
  sync:
    name: Sync
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install shishoctl
        run: |
          SHISHOCTL_URL="https://shisho.dev/releases/shishoctl-0.12.0-x86_64-unknown-linux-gnu"
          sudo curl -L $SHISHOCTL_URL -o /usr/local/bin/shishoctl
          sudo chmod +x /usr/local/bin/shishoctl

      - name: Sign in
        uses: flatt-security/shisho-cloud-action@v1
        with:
          # FIXME: The bot-id to be entered is described in the Trust Condition setting screen
          bot-id: "BTXXXXXXXXXXXXXXXXXXXXXXXXXX"

      - name: Zip the schemas
        run: zip -r schema.zip $SCHEMA_DIR
        env:
          # FIXME: Replace with the path to the folder containing the schema file you want to reference
          SCHEMA_DIR: docs/proto

      - name: Sync with Shisho Cloud
        run: |
          shishoctl web-application collect-endpoints connectrpc \
            --org $ORG_ID \
            --app $APP_ID \
            --url $ENDPOINT_URL \
            --path schema.zip
        env:
          ORG_ID: ${{ vars.SHISHO_CLOUD_ORG_ID }}
          APP_ID: ${{ vars.SHISHO_CLOUD_APP_ID }}
          ENDPOINT_URL: ${{ vars.SHISHO_CLOUD_CONNECTRPC_ENDPOINT_URL }}

Connect RPC integration uploads multiple schemas as a zip archive. Therefore, specify the path to the folder containing these schemas in {{ path_to_schema_dir }}.

You need to register the following variable to GitHub in addition to the basic settings.

• SHISHO_CLOUD_CONNECTRPC_ENDPOINT_URL Connect RPC Endpoint URL to be used for scanning