add tuts (#468)

Author: adela-bytebase

content/docs/tutorials/github-action-data-masking-part1.md

@@ -0,0 +1,120 @@
+---
+title: Applying Data Masking with GitHub Actions - Part 1
+author: Ningjing
+updated_at: 2024/11/19 18:00
+tags: Tutorial
+integrations: General, API
+level: Advanced
+estimated_time: '30 mins'
+description: 'Learn how to automate database masking policies using GitHub Actions and Bytebase API'
+---
+Bytebase is a database DevSecOps platform designed for developers, security, DBA, and platform engineering teams. While it offers an intuitive GUI for managing database schema changes and access control, some teams may want to integrate Bytebase into their existing DevOps platforms using the [Bytebase API](/docs/api/overview/).
+
+Bytebase provides database [dynamic data masking feature](/docs/security/data-masking/overview/) in the **Enterprise Plan**, which can mask sensitive data in the SQL Editor query result based on the context. It helps organizations to protect sensitive data from being exposed to unauthorized users.
+
+By using GitHub Actions with Bytebase API, you can implement policy-as-code to apply database masking policies when a pull request is merged. This tutorial will guide you through the process.
+
+---
+
+This is Part 1 of our tutorial series on implementing automated database masking using GitHub Actions:
+
+- Part 1: Applying Data Masking with GitHub Actions (this one)
+- Part 2: Customizing Data Masking Algorithm with GitHub Actions
+- Part 3: Data Classification and Global Masking with GitHub Actions
+
+## Overview
+
+In this tutorial, you'll learn how to automate database masking policies using GitHub Actions and the Bytebase API. This integration allows you to:
+
+- Manage data masking rules as code
+- Automatically apply masking policies when PRs are merged
+
+Here is [a merged pull request](https://github.com/bytebase/database-security-github-actions-example/pull/5) as an example.
+
+<HintBlock type="info">
+
+The complete code for this tutorial is available at: [database-security-github-actions-example](https://github.com/bytebase/database-security-github-actions-example)
+
+</HintBlock>
+
+## Prerequisites
+
+Before you begin, make sure you have:
+- [Docker](https://www.docker.com/) installed
+- A [GitHub](https://github.com/) account
+- An[ngrok](http://ngrok.com/) account
+- Bytebase Enterprise Plan subscription
+
+## Setup Instructions
+
+### Step 1 - Start Bytebase in Docker and set the External URL generated by ngrok
+
+<IncludeBlock url="/docs/get-started/install/vcs-with-ngrok"></IncludeBlock>
+
+### Step 2 - Create Service Account
+
+<IncludeBlock url="/docs/share/tutorials/create-service-account"></IncludeBlock>
+
+### Step 3 - Prepare Test Data
+
+1. Bytebase by default provides a project `Sample Project` with two database `hr_test` and `hr_prod`.
+1. Click **IAM & Admin > Users & Groups** on the left sidebar. Add users: `[email protected]`, `[email protected]` and `[email protected]` with no roles.
+1. Add a group `[email protected]` with `[email protected]` as a member.
+1. Go to project `Sample Project`, click **Manage > Members** on the left sidebar.
+1. Click **Grant Access** and select users `[email protected]` and `[email protected]` with `Developer` role and group `[email protected]` with `Querier` role.
+
+### Step 4 - Configure GitHub Actions
+
+1. Go to [Database Security GitHub Actions Example](https://github.com/bytebase/database-security-github-actions-example) and clone it.
+
+1. Click **Settings** and then click **Secrets and variables > Actions**. Add the following secrets:
+
+   - `BYTEBASE_URL`: ngrok external URL
+   - `BYTEBASE_SERVICE_KEY`: `[email protected]`
+   - `BYTEBASE_SERVICE_SECRET`: service key copied in previous step
+
+## Understanding the Workflow
+
+Let's dig into the GitHub Actionsworkflow [code](https://github.com/bytebase/database-security-github-actions-example/blob/main/.github/workflows/bb-masking-1.yml):
+
+1. **Trigger**: Workflow runs when PRs are merged to `main`.
+
+1. **Authentication**: The step `Login Bytebase` will log in Bytebase using an action [bytebase-login](https://github.com/marketplace/actions/bytebase-login). The variables you configured in the GitHub **Secrets and variables** are mapped to the variables in the action.
+
+1. **File Detection**: The step `Get changed files` will monitor the changed files in the pull request. For this workflow, we only care about column masking and masking exception. So `masking/databases/**/**/column-masking.json` and `masking/projects/**/masking-exception.json` are filtered out.
+
+1. **Apply Masking Columns**: Then step `Apply column masking` will apply the column masking to the database. First it will parse all the column masking files and then do a loop to apply the column masking to the database one by one. The code it calls Bytebase API is as follows:
+
+   ```bash
+   response=$(curl -s -w "\n%{http_code}" --request PATCH "${BYTEBASE_API_URL}/instances/${INSTANCE_NAME}/databases/${DATABASE_NAME}/policies/masking?allow_missing=true&update_mask=payload" \
+   --header "Authorization: Bearer ${BYTEBASE_TOKEN}" \
+   --header "Content-Type: application/json" \
+   --data @"$CHANGED_FILE")
+   ```
+
+1. **Apply Masking Exceptions**: The step `Apply masking exception` will apply the masking exception to the database and the process is similar, the code it calls Bytebase API is as follows:
+
+   ```bash
+   response=$(curl -s -w "\n%{http_code}" --request PATCH "${BYTEBASE_API_URL}/projects/${PROJECT_NAME}/policies/masking_exception?allow_missing=true&update_mask=payload" \
+   --header "Authorization: Bearer ${BYTEBASE_TOKEN}" \
+   --header "Content-Type: application/json" \
+   --data @"$CHANGED_FILE")
+   ```
+
+1. **PR Feedback**: The step `Comment on PR` will comment on the merged pull to notify the result.
+
+## Verifying the Setup
+
+1. Create and merge a test PR with masking changes.
+
+1. Log in Bytebase console, at the workspace level, click **Data Access > Data Masking**. Click **Explicit Masked Columns**, you can see the column masking is applied to the database.
+
+   ![bb-column-masking](/content/docs/tutorials/github-action-data-masking-part1/bb-column-masking.webp)
+
+1. Go to the project `Sample Project`, click **Database > Masking Access**, you can see the masking exception is applied to the database.
+
+   ![bb-masking-exception](/content/docs/tutorials/github-action-data-masking-part1/bb-masking-exception.webp)
+
+## Next Steps
+
+Now you have successfully applied data masking policies using GitHub Actions and Bytebase API. In the next part of this tutorial, you'll learn how to customize the masking algorithm. Stay tuned!