method-security · sean-hacker · Jun 17, 2024 · Jun 16, 2024 · Jun 16, 2024 · Jun 17, 2024
diff --git a/.github/workflows/mkdocs-develop.yml b/.github/workflows/mkdocs-develop.yml
@@ -0,0 +1,41 @@
+name: 📖 Deploy Dev Docs
+on:
+  push:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+    branches:
+      - develop
+jobs:
+  build-documents:
+    name: Test Documentation Build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # mkdocs gh-deploy requires write permissions to create a new branch
+    steps:
+      - name: Checkout
+        uses: actions/[email protected]
+        with:
+          fetch-depth: 0
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          pip install -r docs/build/requirements.txt
+      - name: Test Build
+        run: mkdocs build --verbose --strict
+      - name: Deploy Docs
+        run: mkdocs gh-deploy --force
diff --git a/.github/workflows/test-docs.yml b/.github/workflows/test-docs.yml
@@ -0,0 +1,37 @@
+name: 📙 Test docs
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+jobs:
+  build-documents:
+    name: Test Documentation Build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read # Not required for public repositories, but for clarity
+    steps:
+      - name: Checkout
+        uses: actions/[email protected]
+        with:
+          fetch-depth: 0
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          pip install -r docs/build/requirements.txt
+      - name: Test Build
+        run: mkdocs build --verbose --strict
diff --git a/.gitignore b/.gitignore
@@ -31,5 +31,8 @@ go.work.sum
 .env/
 !.env/example.env
 
+# mkdocs
+/site
+
 # Don't ignore vendors
 !vendor/**
diff --git a/README.md b/README.md
@@ -1 +1,48 @@
 # Gitlabctl
+
+gitlabctl offers security teams a way to tie Gitlab primitives into their security workflows, ensuring that they leverage those primitives within their security automation pipelines. Designed with data-modeling and data-integration needs in mind, gitlabctl can be used on its own as an interactive CLI, orchestrated as part of a broader data pipeline, or leveraged from within the Method Platform.
+
+The types of scans that gitlabctl can conduct are constantly growing. For the most up to date listing, please see the documentation [here](https://method-security.github.io/gitlabctl/docs/index.html)
+
+To learn more about gitlabctl, please see the [Documentation site](https://method-security.github.io/gitlabctl/) for the most detailed information.
+
+## Quick Start
+
+### Get gitlabctl
+
+For the full list of available installation options, please see the [Installation](./getting-started/installation.md) page. For convenience, here are some of the most commonly used options:
+
+- `docker run methodsecurity/gitlabctl`
+- `docker run ghcr.io/method-security/gitlabctl`
+- Download the latest binary from the [Github Releases](https://github.com/Method-Security/gitlabctl/releases/latest) page
+- [Installation documentation](./getting-started/installation.md)
+
+### General Usage
+
+```bash
+gitlabctl portscan <target>
+```
+
+#### Examples
+
+```bash
+gitlabctl projects --group-id <group> --mine false --base-url https://gitlab.com/api/v4
+```
+
+## Contributing
+
+Interested in contributing to gitlabctl? Please see our organization wide [Contribution](https://method-security.github.io/community/contribute/discussions.html) page.
+
+## Want More?
+
+If you're looking for an easy way to tie gitlabctl into your broader cybersecurity workflows, or want to leverage some autonomy to improve your overall security posture, you'll love the broader Method Platform.
+
+For more information, visit us [here](https://method.security)
+
+## Community
+
+gitlabctl is a Method Security open source project.
+
+Learn more about Method's open source source work by checking out our other projects [here](https://github.com/Method-Security) or our organization wide documentation [here](https://method-security.github.io).
+
+Have an idea for a Tool to contribute? Open a Discussion [here](https://github.com/Method-Security/Method-Security.github.io/discussions).
diff --git a/cmd/projects.go b/cmd/projects.go
@@ -5,6 +5,8 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// InitProjectsCmd initializes the projects command for the gitlabctl CLI. This command sets up the flags for the command,
+// parsing the provided group ID, archived, and mine flags before passing them to the projects package for enumeration.
 func (a *Gitlabctl) InitProjectsCmd() {
 	options := projects.EnumerateProjectsOptions{
 		Mine:     true,

diff --git a/cmd/root.go b/cmd/root.go
@@ -1,3 +1,6 @@
+// Package cmd implements the CobraCLI commands for the methodaws CLI. Subcommands for the CLI should all live within
+// this package. Logic should be delegated to internal packages and functions to keep the CLI commands clean and
+// focused on CLI I/O.
 package cmd
 
 import (
@@ -15,6 +18,9 @@ import (
 	"github.com/xanzy/go-gitlab"
 )
 
+// Gitlabctl is the main struct for the gitlabctl CLI. It contains the version, root flags, output config, output signal,
+// information, providing a context for subcommands to leverage during execution. The output signal is used to write the
+// output of the command to the desired output format and location.
 type Gitlabctl struct {
 	Version          string
 	RootFlags        config.RootFlags
@@ -27,6 +33,8 @@ type Gitlabctl struct {
 	GitlabClient     *gitlab.Client
 }
 
+// NewGitlabctl creates a new Gitlabctl struct with the provided version. The root flags, output config, and output format.
+// We pass the version in here from our main.go file, where we set the version string during the build process.
 func NewGitlabctl(version string) *Gitlabctl {
 	gitlabctl := Gitlabctl{
 		Version: version,
@@ -42,6 +50,12 @@ func NewGitlabctl(version string) *Gitlabctl {
 	return &gitlabctl
 }
 
+// InitRootCommand initializes the root command for the gitlabctl CLI. This command sets up the persistent flags for the
+// CLI, including the quiet, verbose, base-url, token, output-file, and output flags. The root command also sets up the
+// version command, which prints the version of the gitlabctl CLI.
+// The root command sets the PersistentPreRunE, which is responsible for initializing the output signal, as well as creating
+// the Gitlab client that will be used in all commands. The PersistentPostRunE is responsible for writing the output of the
+// command to the desired output format and location.
 func (a *Gitlabctl) InitRootCommand() {
 	var outputFormat string
 	var outputFile string

diff --git a/cmd/vulnerability.go b/cmd/vulnerability.go
@@ -5,6 +5,8 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// InitVulnerabilityCmd initializes the vulnerability command for the gitlabctl CLI. This command sets up the flags for the
+// command, parsing the provided state and severity filters before passing them to the vulnerability package for enumeration.
 func (a *Gitlabctl) InitVulnerabilityCmd() {
 	projectID := 0
 	severities := make([]string, 0)

diff --git a/docs/build/Dockerfile b/docs/build/Dockerfile
@@ -0,0 +1,3 @@
+FROM squidfunk/mkdocs-material:9.4.6
+COPY requirements.txt .
+RUN pip install -r requirements.txt
diff --git a/docs/build/requirements.txt b/docs/build/requirements.txt
@@ -0,0 +1,3 @@
+mkdocs==1.6.0
+mkdocs-material==9.5.26
+Jinja2==3.1.4
diff --git a/docs/community/community.md b/docs/community/community.md
@@ -0,0 +1,7 @@
+# Contributing
+
+For more information on how to get involved in the Method community, please see our organization wide documentation:
+
+- [Discussions](https://method-security.github.io/community/contribute/discussions.html)
+- [Issues](https://method-security.github.io/community/contribute/issues.html)
+- [Pull Requests](https://method-security.github.io/community/contribute/pr.html)
diff --git a/docs/development/adding.md b/docs/development/adding.md
@@ -0,0 +1,10 @@
+# Adding a new capability
+
+By design, gitlabctl breaks every unique network scan into its own top level command. If you are looking to add a brand new capability to the tool, you can take the following steps.
+
+1. Add a file to `cmd/` that corresponds to the sub-command name you'd like to add to the `gitlabctl` CLI
+2. You can use `cmd/projects.go` as a template
+3. Your file needs to be a member function of the `gitlabctl` struct and should be of the form `Init<cmd>Command`
+4. Add a new member to the `gitlabctl` struct in `cmd/root.go` that corresponsds to your command name. Remember, the first letter must be capitalized.
+5. Call your `Init` function from `main.go`
+6. Add logic to your commands runtime and put it in its own package within `internal` (e.g., `internal/projects`)
diff --git a/docs/development/principles.md b/docs/development/principles.md
@@ -0,0 +1,11 @@
+# Project Principles
+
+## Pre-run -> Run -> Post-run
+
+In the root command, we set a `PersistentPreRunE` and `PersistentPostRunE` function that is responsible for initializing the output format and Signal data (in the pre-run) and then write that data in the proper format (in the post-run).
+
+Within the Run command that every command must implement, the output of the collected data needs to be written back to the struct's `OutputSignal.Content` value in order to be properly written out to the caller.
+
+## Cmd vs Internal
+
+By design, the functionality within each command should focus around parsing the variety of flags and options that the command may need to control capability, passing off all real logic into internal modules.
diff --git a/docs/development/setup.md b/docs/development/setup.md
@@ -0,0 +1,43 @@
+# Development Setup
+
+## Adding a new capability
+
+To add a new scan to gitlabctl, providing new enumeration capabilities to security operators everywhere, please see the [adding a new capability](./adding.md) page.
+
+## Setting up your development environment
+
+If you've just cloned gitlabctl for the first time, welcome to the community! We use Palantir's [godel](https://github.com/palantir/godel) to streamline local development and [goreleaser](https://goreleaser.com/) to handle the heavy lifting on the release process.
+
+To get started with godel, you can run
+
+```bash
+./godelw verify
+```
+
+This will run a number of checks for us, including linters, tests, and license checks. We run this command as part of our CI pipeline to ensure the codebase is consistently passing tests.
+
+## Building the CLI
+
+We can use godel to build our CLI locally by running
+
+```bash
+./godelw build
+```
+
+You should see output in `out/build/gitlabctl/<version>/<os>-<arch>/gitlabctl`.
+
+If you'd like to clean this output up, you can run
+
+```bash
+./godelw clean
+```
+
+## Testing releases locally
+
+We can use goreleaser locally as well to test our builds. As gitlabctl uses [cosign](https://github.com/sigstore/cosign) to sign our artifacts and Docker containers during our CI pipeline, we'll want to skip this step when running locally.
+
+```bash
+goreleaser release --snapshot --clean --skip sign
+```
+
+This should output binaries, distributable tarballs/zips, as well as docker images to your local machine's Docker registry.
diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -0,0 +1,29 @@
+# Capabilities
+
+gitlabctl integrates with the Gitlab API to provide security teams with insights into Gitlab primitives and security concepts, allowing teams to leverage the valuable data that Gitlab is generating about their projects. Each of the below pages offers an in depth look at a specific gitlabctl capability related to a different facet of Gitlab that can be enumerated.
+
+- [Projects](./projects.md)
+- [Vulnerabilities](./vulnerabilities.md)
+
+## Top Level Flags
+
+gitlabctl has several top level flags that can be used on any subcommand. These include:
+
+```bash
+Flags:
+      --base-url string      Base URL for Gitlab API. (e.g. https://gitlab.com/api/v4)
+  -h, --help                 help for gitlabctl
+  -o, --output string        Output format (signal, json, yaml). Default value is signal (default "signal")
+  -f, --output-file string   Path to output file. If blank, will output to STDOUT
+  -q, --quiet                Suppress output
+      --token string         Gitlab Access Token. Can also be set via GITLAB_TOKEN environment variable
+  -v, --verbose              Verbose output
+```
+
+## Version Command
+
+Run `gitlabctl version` to get the exact version information for your binary
+
+## Output Formats
+
+For more information on the various output formats that are supported by gitlabctl, see the [Output Formats](https://method-security.github.io/docs/output.html) page in our organization wide documentation.
diff --git a/docs/docs/projects.md b/docs/docs/projects.md
@@ -0,0 +1,33 @@
+# Projects
+
+The `gitlabctl projects` command provides information about Gitlab projects (i.e. repositories) that your token has access to. This project information is a critical element of automating a variety of static code analysis workflows.
+
+## Usage
+
+```bash
+gitlabctl projects --base-url https://gitlab.com/api/v4 --group-id <group id> --output json
+```
+
+## Help Text
+
+```bash
+$ gitlabctl projects -h
+Enumerate Gitlab projects
+
+Usage:
+  gitlabctl projects [flags]
+
+Flags:
+      --archived          Include archived projects
+      --group-id string   Group ID
+  -h, --help              help for projects
+      --mine              Include only projects owned by the authenticated user. (default true)
+
+Global Flags:
+      --base-url string      Base URL for Gitlab API. (e.g. https://gitlab.com/api/v4)
+  -o, --output string        Output format (signal, json, yaml). Default value is signal (default "signal")
+  -f, --output-file string   Path to output file. If blank, will output to STDOUT
+  -q, --quiet                Suppress output
+      --token string         Gitlab Access Token. Can also be set via GITLAB_TOKEN environment variable
+  -v, --verbose              Verbose output
+```
diff --git a/docs/docs/vulnerabilities.md b/docs/docs/vulnerabilities.md
@@ -0,0 +1,36 @@
+# Vulnerabilities
+
+The `gitlabctl vulnerabilities` command allows you to leverage Gitlab's [application security](https://docs.gitlab.com/ee/user/application_security/) capabilities within your automation workflows, ensuring your team has visibility into the entire swathe of vulnerabilities that affect your applications.
+
+## Usage
+
+```bash
+gitlabctl vulnerabilities --base-url https://gitlab.com/api/v4 --project <project id> --output json
+```
+
+## Help Text
+
+```bash
+$ gitlabctl vulnerabilities -h
+Enumerate Gitlab vulnerabilities
+
+Usage:
+  gitlabctl vulnerabilities [flags]
+
+Aliases:
+  vulnerabilities, vulns
+
+Flags:
+  -h, --help                 help for vulnerabilities
+      --project int          Project ID
+      --severities strings   Vulnerability severities. Valid values are 'unknown', 'info', 'low', 'medium', 'high', 'critical'.
+      --states strings       Vulnerability states. Valid values are 'detected', 'dismissed', 'resolved'. If no values are provided, 'detected' will be used by default.
+
+Global Flags:
+      --base-url string      Base URL for Gitlab API. (e.g. https://gitlab.com/api/v4)
+  -o, --output string        Output format (signal, json, yaml). Default value is signal (default "signal")
+  -f, --output-file string   Path to output file. If blank, will output to STDOUT
+  -q, --quiet                Suppress output
+      --token string         Gitlab Access Token. Can also be set via GITLAB_TOKEN environment variable
+  -v, --verbose              Verbose output
+```