Merge pull request #6864 from snyk/docs/agents.md

[j-luong]

docs: adding basic agents.md

Pull Request Submission Checklist

• Follows CONTRIBUTING guidelines
• Commit messages
  are release-note ready, emphasizing
  what was changed, not how.
• Includes detailed description of changes
• Contains risk assessment (Low | Medium | High)
• Highlights breaking API changes (if applicable)
• Links to automated tests covering new functionality
• Includes manual testing instructions (if necessary)
• Updates relevant GitBook documentation (PR link: ___)
• Includes product update to be announced in the next stable release notes

What does this PR do?

This PR adds some new instrumentation data to measure how we perform organisation lookups in GAF.

Where should the reviewer start?

Related GAF PR

How should this be manually tested?

Run the following commands and check for the instrumentation entry:

command: `snyk test --org=86616ead-043b-4ef3-8c8d-81ecdf5ac751 -d` // valid UUID but org does not exist
instrumentation: "gaf.app.defaultfunc.organization.lookup": "provided_id" // should be "provided_id_failed"

command: `snyk test --org=be9221c6-5f63-4339-a07e-43d38b3ecb8z -d` // this is not actually a valid UUID and will be considered a slugname in code
instrumentation: "gaf.app.defaultfunc.organization.lookup": "provided_slug_failed"

command: `snyk test --org=<VALID_ORG_ID> -d` // valid UUID and org exists
instrumentation: "gaf.app.defaultfunc.organization.lookup": "provided_id"

command: `snyk test --org=<VALID_ORG_SLUG> -d`
instrumentation: "gaf.app.defaultfunc.organization.lookup": "provided_slug"

command: `snyk test --org=fake -d`
instrumentation: "gaf.app.defaultfunc.organization.lookup": "provided_slug_failed"

command: `snyk test -d`
instrumentation: "gaf.app.defaultfunc.organization.lookup": "default"

Note that:

command: `snyk test --org=86616ead-043b-4ef3-8c8d-81ecdf5ac751 -d` // valid UUID but org does not exist
instrumentation: "gaf.app.defaultfunc.organization.lookup": "provided_id" // should be "provided_id_failed"

Outputs the wrong instrumentation data as outlined in RFC: Consistent Organization Resolution.

What's the product update that needs to be communicated to CLI users?

N/A - internal change

Risk assessment (Low | Medium | High)?

Low - changes to instrumentation data

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[j-luong]

context: writeLogHeader will call config.GetString(configuration.ORGANIZATION) before analytics are initialised, so we move it to just after globalEngine.Init()

[danskmt]

I wonder if the goal is to call config.GetString(configuration.ORGANIZATION), maybe we should do it explicitly here? wdyt?

[j-luong]

I think its right where it currently is, config.GetString(configuration.ORGANIZATION) fetches the configured org so should be called close to where it is going to be used - which is in writeLogHeader()

[github-actions]

	Warnings
⚠️	There are multiple commits on your branch, please squash them locally before merging!

Generated by 🚫 dangerJS against bd8fe93

[snyk-pr-review-bot]

PR Reviewer Guide 🔍

🧪 No relevant tests

🔒 Security concerns Sensitive information exposure: The change in cliv2/pkg/core/main.go explicitly adds the user's Organization ID and Organization Slug to a list of terms that are exempted from the log scrubbing process. This will cause sensitive customer identifiers to leak into debug logs whenever the CLI is run with --debug or the DEBUG environment variable.

⚡ Recommended focus areas for review Log Context Loss 🟡 [minor] Moving writeLogHeader to after globalEngine.Init() creates a gap in log visibility. If globalEngine.Init() fails, it returns an error and the function exits at line 622. In this scenario, any logs generated during initialization or the failure itself will be missing the diagnostic header information (version, environment, etc.), making troubleshooting harder. writeLogHeader(globalConfiguration, networkAccess)

📚 Repository Context Analyzed This review considered 8 relevant code sections from 5 files (average relevance: 0.94) scripts/upgrade-snyk-go-dependencies.go (lines 1-149) CONTRIBUTING.md (lines 231-409) cliv2/scripts/prepare_licenses.go (lines 1-189) package-lock.json (2 segments, lines 3216-3482) cliv2/pkg/core/main.go (3 segments, lines 527-726)

🤖 Repository instructions applied (from AGENTS.md)

[robertolopezlopez]

I think the PR description (docs: adding basic agents.md) does not correspond with the diff @j-luong