AI Agent Policy as Code

Agent security policy should be reviewable in the same pull request as the agent configuration. Foo Guard reads .fooguard.yml from the repository and uses it as repository policy-as-code: which paths to scan, which severity fails the scan, and which letter grade is too low.

That file is not a list of suppressed rules, and it is not a runtime policy for a live agent. It governs pre-deployment scanning and CI gates. Organization policy, set in the Team workspace, remains a mandatory floor that repository settings cannot weaken.

A repository policy file

Version 1 of the file supports scan selection, policy thresholds, and size limits:

version: 1

scan:
  paths:
    - agents/
  include:
    - "**/*.yaml"
    - "**/*.json"
  exclude:
    - "**/fixtures/**"

policy:
  failOn: high        # critical | high | medium
  minGrade: B         # optional: A | B | C | D | F

limits:
  maxFiles: 50
  maxFileBytes: 524288
  maxTotalBytes: 10485760

failOn fails the scan when a finding is at or above that severity. minGrade fails the scan when the risk grade is worse than the letter you set. Risk grades run from A to F, and a higher risk score is worse. scan.paths, include, and exclude choose files. limits caps how many files and bytes a repository scan will accept.

Allowlists, blocklists, and per-rule suppressions are not part of this file. If a rule fires, the way to clear it is to change the configuration or to accept a failing policy result. You cannot turn the rule off in YAML.

Which source wins

Foo Guard merges every source it has and keeps the strictest threshold:

• Organization policy, configured in the Team workspace and kept with an audit history
• Repository policy in .fooguard.yml at the scanned commit
• CLI flags such as --fail-on and --min-grade for one run
• The product default, failOn: high, when nothing else is set

If the organization requires failOn: high and the repository file says failOn: medium, medium wins because it is stricter. A repository file cannot drop the organization down to critical-only. The GitHub check summary names the effective threshold and where it came from.

Review the policy change itself

Because .fooguard.yml is an ordinary file, a change to minGrade or to scan.exclude shows up in the pull request. Team scans read the file at that commit SHA, so the policy under review is the policy that produces the Foo Guard Security check. The CLI reads the working tree when you run it locally or in CI.

The legacy filename .agentguard.yml is still accepted. Prefer .fooguard.yml in new repositories.

Changing the bar in a pull request

Raising minGrade from C to B is a policy change, and it belongs in Git next to the agent files it will judge. Reviewers can see that the repository will now fail grades C, D, and F. They can also see a new scan.exclude entry that would hide a directory. Team scanning uses the file at the pull request SHA, so the Foo Guard Security check on that pull request is already applying the proposed threshold.

Organization policy stays outside the file on purpose. A workspace admin sets the floor in Foo Guard, and the change is written to the workspace audit log. A developer cannot relax that floor by editing YAML. They can make the repository stricter. CLI flags work the same way for a single job: they can tighten the run, and they cannot undercut the organization.

Policy is only useful with a scanner

Thresholds do nothing until a scan runs. Start with the AI agent security scanner to see findings, then encode the threshold you are willing to merge. Wire the file into GitHub and CI so the next configuration change is judged against it. The field reference is .fooguard.yml, and organization policy is described in posture and organization policy.

Read the .fooguard.yml reference