ci: add markdown link checker in workflow #544

[SabarishMN]

Description

This PR addresses issue #544 by adding an automated GitHub Action workflow to validate markdown links within the repository.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Maintenance (dependency updates, CI/CD, refactoring)
• Security fix

Package(s) Affected

• agent-os-kernel
• agent-mesh
• agent-runtime
• agent-sre
• agent-governance
• docs / root

Checklist

• My code follows the project style guidelines (ruff check)
• I have added tests that prove my fix/feature works
• All new and existing tests pass (pytest)
• I have updated documentation as needed
• I have signed the Microsoft CLA

Related Issues

Fixes #544

[github-actions]

Welcome to the Agent Governance Toolkit! Thanks for your first pull request.
Please ensure tests pass, code follows style (ruff check), and you have signed the CLA.
See our Contributing Guide.

[github-actions]

🤖 AI Agent: code-reviewer

Review Feedback

This pull request introduces a GitHub Actions workflow to validate markdown links in the repository. While this is a maintenance-focused addition, it indirectly contributes to the project's security and reliability by ensuring documentation integrity. Below is the detailed review:

---

🔴 CRITICAL

No critical issues identified in this PR.

---

🟡 WARNING

1. Backward Compatibility:
   • The workflow triggers on pull_request events for markdown files (**/*.md). If the repository contains markdown files that are dynamically generated or excluded from version control, this workflow might not account for them. Ensure this does not inadvertently affect contributors or CI/CD processes.

---

💡 SUGGESTION

1. Workflow Robustness:

   • The lycheeverse/lychee-action is pinned to version v1.9.0. While this is good practice, consider using a SHA-based pinning for additional security against supply chain attacks. For example:

     uses: lycheeverse/lychee-action@<SHA>

   • Alternatively, you could configure Dependabot to monitor GitHub Actions dependencies for updates.

2. Error Reporting:

   • The args field includes --verbose, which is helpful for debugging. However, consider adding a mechanism to summarize the errors (e.g., number of broken links) for better visibility in the CI logs.

3. Fail Behavior:

   • The fail: true configuration ensures the workflow fails if broken links are detected. This is appropriate for pull requests but might be overly strict for workflow_dispatch runs. Consider adding a conditional flag to allow manual runs without failing the workflow.

4. Documentation:

   • Update the repository's CONTRIBUTING.md file to inform contributors about this new CI check. This will help them proactively fix broken links before submitting pull requests.

5. Testing:

   • While this workflow does not directly affect the Python packages, it would be prudent to test the workflow on a branch with intentionally broken links to ensure it behaves as expected.

6. Exclusion Rules:

   • The --exclude-loopback flag excludes localhost links. If there are other types of links (e.g., internal links or links to private resources) that should be excluded, consider adding them explicitly to the configuration.

7. Caching:

   • To optimize performance, consider caching the results of the link checker for unchanged files across runs. This can reduce unnecessary checks and improve CI efficiency.

---

Summary

This PR is a solid addition to the CI/CD pipeline for improving documentation quality. Addressing the suggestions above will enhance the workflow's robustness and usability. No critical security or breaking changes were identified.

[github-actions]

🤖 AI Agent: contributor-guide — Welcome! 🎉

Welcome! 🎉

Hi there, and welcome to the microsoft/agent-governance-toolkit community! Thank you so much for taking the time to contribute. It's always exciting to see new contributors, and we’re thrilled to have you here. 😊

What You Did Well 🌟

First off, great job on:

1. Clear Description: Your PR description is well-structured and provides all the necessary details, including the issue it addresses (ci: add markdown link checker to CI #544) and the type of change. This makes it easy for reviewers to understand your intent.
2. Thoughtful Workflow Addition: Adding a markdown link checker is a fantastic idea for improving the quality of our documentation. It’s a proactive step to ensure that broken links don’t creep into the repository.
3. Use of Existing Actions: Leveraging lycheeverse/lychee-action and tj-actions/changed-files is a smart choice. These are well-maintained tools that align with our CI/CD practices.

Suggestions for Improvement ✨

Here are a few suggestions to make your contribution even better:

1. Add a Test Case:

   • While this is a CI/CD change and doesn’t directly involve the codebase, it’s still a good idea to test the workflow. You can do this by including a markdown file with a mix of valid and invalid links in your PR. This will help us verify that the workflow behaves as expected.
   • Once the workflow is verified, you can remove the test markdown file before merging.

2. Project Conventions:

   • We use ruff for linting (configured for E, F, and W rules). While this doesn’t directly apply to your YAML file, it’s good to ensure your PR passes all checks, including linting.
   • For commit messages, we follow the Conventional Commits standard. Your commit message ci: add markdown link checker in workflow is already aligned with this convention — great job! 🎉

3. Documentation Update:

   • Since this PR introduces a new workflow, it would be helpful to update the CONTRIBUTING.md file to let future contributors know about the markdown link checker. You can add a short section explaining that markdown files will be automatically checked for broken links during PRs.

4. Security Considerations:

   • While this PR doesn’t involve sensitive code, it’s always good to double-check that external actions (like lycheeverse/lychee-action and tj-actions/changed-files) are from trusted sources. Both of these are widely used and well-maintained, so they look good to me.

Resources to Help You 📚

Here are some resources that might be helpful as you continue contributing:

• CONTRIBUTING.md: Our guide for contributing to this project.
• QUICKSTART.md: A quick guide to get up and running with the project.

Next Steps 🚀

1. Address the suggestions above (e.g., add a test markdown file with links, update CONTRIBUTING.md).
2. Push your changes to this branch — the CI/CD pipeline will automatically run again.
3. Once you’ve made the updates, let us know by leaving a comment here. A maintainer will review your changes and provide feedback or approve the PR.

Thank you again for your contribution! If you have any questions or need help, don’t hesitate to ask. We’re here to support you. 😊

Looking forward to seeing your updates! 🚀

[github-actions]

🤖 AI Agent: security-scanner — Security Analysis of PR #544

Security Analysis of PR #544

This PR introduces a GitHub Actions workflow to validate markdown links in the repository. While this is a maintenance change and does not directly impact the core functionality of the microsoft/agent-governance-toolkit, it is still important to ensure that the new workflow does not introduce any security vulnerabilities.

---

Findings

1. Potential Credential Exposure in Logs

Risk: 🔴 CRITICAL
The lycheeverse/lychee-action is configured with the --verbose flag. This flag can cause sensitive information, such as URLs containing credentials or tokens, to be logged in the GitHub Actions logs. If these logs are publicly accessible or shared, it could lead to credential exposure.

Attack Vector:
If any markdown file contains a URL with embedded credentials (e.g., https://username:password@domain.com), the --verbose flag could log this URL in plaintext, exposing the credentials to anyone with access to the logs.

Suggested Fix:

• Remove the --verbose flag unless absolutely necessary. If detailed logs are required for debugging, ensure that logs are sanitized to redact sensitive information.
• Add a pre-check to sanitize URLs in markdown files before passing them to the link checker.

---

2. Supply Chain Risk: Dependency on External Actions

Risk: 🟠 HIGH
The workflow depends on two third-party GitHub Actions:

• tj-actions/changed-files@v44
• lycheeverse/lychee-action@v1.9.0

These dependencies could introduce a supply chain risk if the maintainers of these actions are compromised or if malicious code is introduced in future versions.

Attack Vector:
An attacker could compromise the tj-actions or lycheeverse repositories and inject malicious code into their actions. This malicious code would then execute in the context of the GitHub Actions runner, potentially exposing repository secrets or modifying the repository.

Suggested Fix:

• Pin dependencies to a specific commit SHA instead of a version tag (e.g., @v1.9.0). This ensures that the exact version of the action is used and prevents unexpected changes from upstream.
• Regularly audit the third-party actions for security vulnerabilities or suspicious activity.

---

3. Improper Input Handling for lychee-action

Risk: 🟡 MEDIUM
The lychee-action is passed the output of changed-files.outputs.all_changed_files directly as an argument. If this output is not properly sanitized, it could lead to command injection or unexpected behavior.

Attack Vector:
If an attacker is able to manipulate the contents of changed-files.outputs.all_changed_files (e.g., through a specially crafted branch name or file path), they could inject malicious arguments into the lychee-action command.

Suggested Fix:

• Validate and sanitize the all_changed_files output before passing it to the lychee-action.
• Use a safer method to pass file paths, such as writing them to a temporary file and passing the file path to lychee-action.

---

4. Lack of Restriction on Workflow Execution

Risk: 🟡 MEDIUM
The workflow triggers on all pull requests that modify markdown files. If a malicious actor creates a pull request from a fork, the workflow could execute untrusted code in the context of the repository.

Attack Vector:
An attacker could create a fork of the repository, modify the workflow file to include malicious code, and open a pull request. The workflow would then execute the attacker's code in the context of the repository.

Suggested Fix:

• Use the pull_request_target event instead of pull_request to ensure that the workflow runs in the context of the base repository, not the fork.
• Restrict the permissions of the GitHub Actions token to the minimum required for the workflow (e.g., read-only for the repository).

---

Summary of Findings

Finding	Risk	Suggested Fix
Credential exposure in logs	🔴 CRITICAL	Remove --verbose flag or sanitize logs to redact sensitive information.
Supply chain risk from external actions	🟠 HIGH	Pin dependencies to specific commit SHAs and audit third-party actions regularly.
Improper input handling for lychee-action	🟡 MEDIUM	Validate and sanitize all_changed_files output before passing to the action.
Lack of restriction on workflow execution	🟡 MEDIUM	Use pull_request_target and restrict GitHub Actions token permissions.

---

Final Recommendation

While this PR primarily introduces a CI/CD maintenance workflow, it has potential security implications due to the use of third-party actions, verbose logging, and input handling. Address the critical and high-risk findings before merging to ensure the security of the repository and its workflows.

[SabarishMN]

@microsoft-github-policy-service agree

[SabarishMN]

@imran-siddique, I've addressed the markdown link issues in this PR. Could you please take a look and provide a manual review/approval when you have a moment? Thanks!

[github-actions]

🤖 AI Agent: code-reviewer

Review of PR #544: ci: add markdown link checker in workflow

Summary

This PR introduces a GitHub Actions workflow to validate markdown links in the repository using the lychee-action. The workflow is triggered on pull requests that modify .md files and can also be manually triggered via workflow_dispatch.

---

Feedback

🔴 CRITICAL: Security Concerns

1. Untrusted External Links in CI/CD:
   • The lychee-action checks external links, which could potentially expose the CI/CD pipeline to malicious or compromised URLs. This could lead to:
     • Denial of Service (DoS) if the pipeline is overwhelmed by slow or malicious responses.
     • Data leakage if sensitive information is inadvertently sent to external servers.
   • Recommendation: Add a whitelist or domain filtering mechanism to restrict link validation to trusted domains. Alternatively, consider running the link checker in a sandboxed environment.

💡 SUGGESTION: Workflow Optimization

1. Avoid Running on Unchanged Markdown Files:

   • The if: steps.changed-files.outputs.any_changed == 'true' condition ensures the workflow runs only if markdown files are changed. However, the args parameter (${{ steps.changed-files.outputs.all_changed_files }}) passes all changed files, which might include non-markdown files due to misconfiguration.
   • Recommendation: Explicitly filter for .md files in the args parameter to avoid unnecessary checks.

2. Parallel Execution:

   • For repositories with many markdown files, the link checker might take significant time to complete.
   • Recommendation: Investigate whether lychee-action supports parallel execution or batching to improve performance.

💡 SUGGESTION: Error Handling

1. Graceful Failure:
   • The fail: true configuration ensures the workflow fails if broken links are detected. While this is useful for enforcing link correctness, it might block PRs unnecessarily if external links are temporarily down.
   • Recommendation: Consider adding a retry mechanism or marking external link failures as warnings instead of errors.

💡 SUGGESTION: Documentation

1. Workflow Documentation:
   • The PR does not include documentation for the new workflow. Contributors might not be aware of its existence or how to debug failures.
   • Recommendation: Add a section in the repository's CONTRIBUTING.md or README.md explaining the markdown link checker workflow and how to address failures.

🔴 CRITICAL: OWASP Agentic Top 10 Compliance

1. External Dependency Trust:
   • The lychee-action is an external dependency. If this action is compromised, it could introduce vulnerabilities into the CI/CD pipeline.
   • Recommendation: Pin the action version (@v1.9.0) to avoid unexpected updates. Regularly audit the action's repository for security advisories.

🟡 WARNING: Backward Compatibility

1. Impact on Existing PRs:
   • This workflow introduces a new CI/CD check that might fail for existing PRs with broken links, potentially blocking their merge.
   • Recommendation: Communicate this change to contributors and provide a grace period for fixing broken links in existing PRs.

---

Actionable Items

1. 🔴 Add domain filtering or sandboxing to mitigate risks from untrusted external links.
2. 💡 Explicitly filter .md files in the args parameter to avoid unnecessary checks.
3. 💡 Investigate parallel execution or batching for performance improvements.
4. 💡 Add retry mechanisms or mark external link failures as warnings.
5. 💡 Document the workflow in CONTRIBUTING.md or README.md.
6. 🔴 Pin the lychee-action version and audit its repository regularly.
7. 🟡 Communicate the new workflow to contributors and provide a grace period for fixing broken links.

---

Final Assessment

This PR introduces a useful maintenance feature but requires additional safeguards to ensure security and usability. Addressing the critical issues flagged above is essential before merging.

[github-actions]

🤖 AI Agent: code-reviewer

Feedback on PR #544: Adding Markdown Link Checker Workflow

🔴 CRITICAL

No critical issues identified in this PR. The changes are limited to CI/CD workflow updates and do not directly impact the security or functionality of the core packages.

---

🟡 WARNING

1. Potential Breaking Change in CI/CD Workflow:
   • The lycheeverse/lychee-action@v1.9.0 is used for link checking. If this action is deprecated or changes its behavior in future versions, it could break the CI/CD pipeline. Consider pinning the action to a specific commit SHA instead of a version tag (v1.9.0) to ensure stability.

---

💡 SUGGESTIONS

1. Improve Workflow Robustness:

   • The args field in the Run Link Checker step directly passes the list of changed files (${{ steps.changed-files.outputs.all_changed_files }}). If the list of files is empty or improperly formatted, the link checker might fail. Consider adding a fallback mechanism or validation step to ensure the input is always valid.

2. Exclude Known False Positives:

   • The --exclude-loopback flag is used to ignore localhost links. You might also want to exclude other known false positives, such as internal links that are dynamically generated or links to external services that are temporarily unavailable. This can be configured using an exclusion list.

3. Add Documentation for Workflow:

   • Update the repository's CONTRIBUTING.md or equivalent documentation to explain the purpose of this workflow and how contributors can address link-checking failures. This will help new contributors understand the CI/CD process better.

4. Test Workflow on a Variety of Markdown Files:

   • Ensure the workflow has been tested on Markdown files with different types of links (e.g., relative links, absolute links, anchors) to confirm its reliability.

5. Optimize Workflow Trigger:

   • The workflow currently triggers on all Markdown file changes (**/*.md). If the repository contains Markdown files that are not relevant to the project (e.g., archived documentation), consider refining the paths filter to exclude such files.

6. Add a Timeout:

   • To prevent the workflow from hanging indefinitely due to network issues or unresponsive links, consider adding a timeout to the lychee-action step.

---

Summary

This PR introduces a useful maintenance feature to validate Markdown links in the repository. While the implementation is straightforward, there are opportunities to improve robustness and documentation. Addressing the above suggestions will ensure the workflow remains reliable and easy to use for contributors.