Documenting Strict Mode CLI Feature: A Comprehensive Guide

by Admin 59 views
Documenting Strict Mode CLI Feature: A Comprehensive Guide

Hey guys! Let's dive into documenting the strict-mode CLI feature for our project. This guide will walk you through everything you need to know to implement and understand this feature, ensuring we're all on the same page. We'll cover what strict mode does, how to use it, and where to add the necessary documentation. So, buckle up, and let's get started!

Objective

The primary objective here is to add comprehensive reference documentation for the strict-mode CLI feature in the frontmatter reference guide. This ensures that users have clear and detailed instructions on what strict mode entails and how to effectively use it. By providing this documentation, we aim to improve the user experience and enhance the security posture of our project.

Context

The schema consistency audit (Discussion #4177) highlighted that while strict-mode is mentioned in guides/security.md, it lacks detailed documentation in the reference documentation. This omission can lead to confusion and inconsistent usage. Users need clear guidance on what strict mode does and how to use it. This documentation gap directly impacts the usability and security of our project, making it crucial to address it promptly.

Related to #4177.

Current State

Currently, the situation is as follows:

  • Brief mention: docs/src/content/docs/guides/security.md:124-126
  • Missing from: docs/src/content/docs/reference/frontmatter.md
  • Missing from: docs/src/content/docs/setup/cli.md (CLI reference)

This fragmented information makes it difficult for users to get a complete understanding of the strict-mode feature. The lack of dedicated documentation in the reference and CLI documentation means that users must piece together information from various sources, which is inefficient and prone to errors.

Proposed Approach

To address this, we propose adding a dedicated section in the appropriate documentation files:

  1. In frontmatter.md: Add a note indicating that this feature is CLI-only within the "Agentic Workflow Specific Fields" section.
  2. In cli.md: Document the --strict flag with comprehensive details.

This approach ensures that the documentation is both comprehensive and easily accessible, providing users with all the information they need in a clear and structured manner.

Suggested Content Structure

Here’s a suggested structure for the content we'll be adding:

### Strict Mode (CLI-only)

Strict mode enforces enhanced security and validation rules during compilation. Enable via CLI flag:

```bash
gh aw compile --strict

Enforcement Areas:

  • Action Pinning: Requires all GitHub Actions to be pinned to specific commit SHAs
  • Network Permissions: Requires explicit network configuration (no implicit defaults)
  • Write Permissions: Requires use of safe-outputs for GitHub API write operations
  • Bash Tool Restrictions: Restricts wildcard usage in bash tool configurations

Note: Strict mode is a CLI-only feature and cannot be configured in workflow frontmatter.


This structure provides a clear overview of the feature, how to enable it, and the areas of enforcement. The note about it being CLI-only is crucial to prevent confusion. 

## Files to Modify

We need to modify the following files:

-   `docs/src/content/docs/reference/frontmatter.md` - Add CLI-only features note
-   `docs/src/content/docs/setup/cli.md` - Add `--strict` flag documentation
-   Consider adding to `docs/src/content/docs/guides/security.md` - Expand existing mention

By modifying these files, we ensure that the documentation is consistent and comprehensive across all relevant areas of the project. This will help users quickly find the information they need and understand how to use the **strict-mode** feature effectively.

## Acceptance Criteria

To ensure that the documentation meets our standards, we'll use the following acceptance criteria:

-   [ ] Reference documentation includes a **strict-mode** section
-   [ ] Documentation clearly states it's CLI-only
-   [ ] All four enforcement areas are documented
-   [ ] Examples show CLI usage: `gh aw compile --strict`
-   [ ] Cross-references to related security guide sections
-   [ ] Follows Diátaxis framework (reference style)

Meeting these criteria will guarantee that the documentation is accurate, complete, and easy to use. It will also ensure that users have a clear understanding of the **strict-mode** feature and how it enhances the security of their workflows.

## Deep Dive into Strict Mode Enforcement Areas

To truly understand the importance of documenting **strict mode**, let's break down each of the enforcement areas in detail. Each area plays a vital role in enhancing the security and reliability of our workflows, and documenting them clearly is essential for our users. These enforcement areas ensure robust security and validation, and providing clear documentation is paramount. Let's explore them:

### Action Pinning

**Action pinning** is a critical security measure that requires all GitHub Actions to be pinned to specific commit SHAs (Secure Hash Algorithm). This means that instead of referencing an action by its tag or branch, which can be changed, you must specify the exact commit SHA that the action is using. This ensures that the action's code remains consistent and prevents malicious actors from injecting harmful code into your workflows. By enforcing action pinning, we protect our users from supply chain attacks and ensure the integrity of their workflows. This approach guarantees that the action's code remains unchanged, bolstering workflow integrity and protecting against potential supply chain attacks. 

For example, instead of using `actions/checkout@v3`, you would use `actions/checkout@a1e15c7e5f86a44e8a4f804625230b363902b0a`. This explicit reference ensures that you always use the exact version of the action you intend to use. 

**Documenting action pinning** involves explaining why it's necessary, how to implement it, and what the potential risks are if it's not enforced. Users need to understand that while it may require more effort to update actions, the security benefits are well worth the investment. The documentation should include examples of how to pin actions and how to verify that actions are pinned correctly. 

### Network Permissions

**Network permissions** require explicit network configuration, eliminating implicit defaults. By default, many systems allow outbound network connections without specific configuration. In **strict mode**, we require users to explicitly define which network connections are allowed. This reduces the risk of unauthorized access and data exfiltration. Explicitly defining network connections reduces unauthorized access risks and ensures that only necessary connections are permitted. 

For instance, if a workflow needs to access an external API, the user must explicitly define the network permissions for that API. This can be done by specifying the domain and port that the workflow is allowed to access. Without explicit network permissions, the workflow will be blocked from making any outbound connections, preventing potential security breaches. 

**Documenting network permissions** involves explaining how to configure network access for different types of workflows. This includes providing examples of how to define network permissions for common use cases, such as accessing external APIs, downloading dependencies, and communicating with other services. The documentation should also explain the risks of allowing unrestricted network access and the benefits of using **strict mode** to enforce network permissions. 

### Write Permissions

**Write permissions** require the use of safe-outputs for GitHub API write operations. In other words, **strict mode** mandates using secure methods to interact with the GitHub API when making changes. For example, leveraging `safe-outputs` ensures data integrity and prevents unauthorized modifications. 

When a workflow needs to update a file, create a release, or perform any other write operation on the GitHub repository, it must use safe-outputs to ensure that the operation is performed securely. Safe-outputs provide a mechanism for validating and sanitizing the data before it's written to the repository, preventing potential security vulnerabilities. 

**Documenting write permissions** involves explaining how to use safe-outputs for different types of write operations. This includes providing examples of how to validate and sanitize data, how to handle errors, and how to ensure that the write operation is performed securely. The documentation should also explain the risks of using unsafe write operations and the benefits of using **strict mode** to enforce safe write permissions. 

### Bash Tool Restrictions

**Bash tool restrictions** limit wildcard usage in bash tool configurations. Wildcards can be powerful, but they can also be dangerous if not used carefully. In **strict mode**, we restrict the use of wildcards to prevent potential security vulnerabilities and ensure that bash tools are used in a controlled and predictable manner. Restricting wildcard usage prevents unexpected behavior and enhances the overall security of bash tools. 

For example, instead of using `rm -rf *`, which could potentially delete all files in a directory, we require users to specify the exact files that they want to delete. This prevents accidental deletions and ensures that the bash tool is only used to delete the intended files. 

**Documenting bash tool restrictions** involves explaining how to use bash tools safely and effectively in **strict mode**. This includes providing examples of how to avoid using wildcards, how to specify the exact files that you want to operate on, and how to handle errors. The documentation should also explain the risks of using wildcards and the benefits of using **strict mode** to enforce bash tool restrictions. 

## Related Files

For implementation references, you can refer to the following files:

-   `pkg/workflow/compiler.go:111` (SetStrictMode)
-   `pkg/workflow/compiler.go:684` (validateStrictMode)
-   `pkg/workflow/strict_mode.go` (enforcement logic)
-   `pkg/workflow/action_pins.go:110,121` (action pinning enforcement)

Related to #4177

## Conclusion

By following this guide, we can ensure that the **strict-mode** CLI feature is well-documented and easy to use. This will not only improve the user experience but also enhance the security of our project. Remember, clear and comprehensive documentation is key to the success of any feature. So, let's get to it and make sure **strict mode** is a valuable and well-understood part of our project! Let's get this done, team! This will significantly improve the security and usability of our project.