USING.md

• Using MRVA
  • Set up controller repo
  • Use the codeql extension to run MRVA
  • Use custom list with target repos in VS Code
  • Run MRVA from command line
• Miscellaneous Notes
  • Action logs on Controller Repository

Using MRVA

Following are notes to illustrate a full MRVA workflow.

Set up controller repo

Following the instructions, start with manually creating the controller repository

gh repo create mirva-controller --public -d 'Controller for MRVA'

This avoids

An error occurred while setting up the controller repository: Controller
repository "hohn/mirva-controller" not found.

Populate the controller repository

mkdir -p ~/local/mirva-controller && cd ~/local/mirva-controller 
echo "* mirva-controller" >> README.org
git init
git add README.org
git commit -m "first commit"
git branch -M master
git remote add origin git@github.com:hohn/mirva-controller.git
git push -u origin master

This avoids

Variant analysis failed because the controller repository hohn/mirva-controller
does not have a branch 'master'. Please create a 'master' branch by clicking here
and re-run the variant analysis query. 

Use the codeql extension to run MRVA

Following the instructions and running ./FlatBuffersFunc.ql, the entry google/flatbuffers has one result. Others have none.

Use custom list with target repos in VS Code

The json file is in your VS Code workspace. In my case, here:

/Users/hohn/Library/Application Support/Code/User/workspaceStorage/bced2e4aa1a5f78ca07cf9e09151b1af/GitHub.vscode-codeql/databases.json

It can be edited in VS Code using the {} button.

It's saved in the workspace, but not in the current git repository.

Here are two snapshots for reference:

{
    "version": 1,
    "databases": {
        "variantAnalysis": {
            "repositoryLists": [
                {
                    "name": "mirva-list",
                    "repositories": [
                        "google/flatbuffers"
                    ]
                }
            ],
            "owners": [],
            "repositories": []
        }
    },
    "selected": {
        "kind": "variantAnalysisSystemDefinedList",
        "listName": "top_10"
    }
}

or

{
    "version": 1,
    "databases": {
        "variantAnalysis": {
            "repositoryLists": [
                {
                    "name": "mirva-list",
                    "repositories": [
                        "google/flatbuffers"
                    ]
                }
            ],
            "owners": [],
            "repositories": []
        }
    },
    "selected": {
        "kind": "variantAnalysisUserDefinedList",
        "listName": "mirva-list"
    }
}

Run MRVA from command line

1. Install mrva cli

   cd ~/local/gh-mrva
   # Build it
   go mod edit -replace="github.com/GitHubSecurityLab/gh-mrva=/Users/hohn/local/gh-mrva"
   go build
   
   # Install 
   gh extension install .
   
   # Sanity check
   gh mrva -h

2. Set up the configuration

   cd ~/local/gh-mrva
   
   cat > ~/.config/gh-mrva/config.yml <<eof
   # The following options are supported
   # codeql_path: Path to CodeQL distribution (checkout of codeql repo)
   # controller: NWO of the MRVA controller to use
   # list_file: Path to the JSON file containing the target repos
   
   # git checkout codeql-cli/v2.15.5
   codeql_path: /Users/hohn/local/codeql-lib
   controller: hohn/mirva-controller
   list_file: /Users/hohn/local/gh-mrva/databases.json
   
   eof

3. Submit the mrva job

   gh mrva submit --help    
   
   gh mrva submit --language cpp --session mirva-session-1 \
      --list mirva-list                                    \
      --query /Users/hohn/local/gh-mrva/FlatBuffersFunc.ql

4. Check the status and download the sarif files

   cd ~/local/gh-mrva
   
   # Check the status
   gh mrva status --session mirva-session-1
   
   # Download the sarif files when finished
   gh mrva download --session mirva-session-1 \
      --output-dir mirva-session-1-sarif
   
   # Or download the sarif files and CodeQL dbs when finished
   gh mrva download --session mirva-session-1 \
      --download-dbs \
      --output-dir mirva-session-1-sarif

Miscellaneous Notes

Action logs on Controller Repository

The action logs are on the controller repository at https://github.com/hohn/mirva-controller/actions.

The action>google flatbuffers log references

github/codeql-variant-analysis-action

Run actions/checkout@v4
with:
    repository: github/codeql-variant-analysis-action
    ref: main
    token: ***
    ssh-strict: true
    persist-credentials: true
    clean: true
    sparse-checkout-cone-mode: true
    fetch-depth: 1
    fetch-tags: false
    show-progress: true
    lfs: false
    submodules: false
    set-safe-directory: true
    env:
        CODEQL_ENABLE_EXPERIMENTAL_FEATURES_SWIFT: true

This is https://github.com/github/codeql-variant-analysis-action

The workflow producing the logs: https://github.com/github/codeql-variant-analysis-action/blob/main/variant-analysis-workflow.yml