Watch with Guard, then stop rule-breaking calls

Guard first only watches. You see what it would have stopped, and only then do you decide whether it should stop calls. This guide covers both steps.

Before you start

• Guard is for trying in development and staging. It has not been qualified for production traffic.
• Guard’s policy is built from the rules you have reviewed. Review them first with geo rules review <ID> --accept. A rule that Guard cannot decide from a single call is listed with the reason instead of being approximated.
• Guard only sees calls that go through it. See Guard.

Set Guard up to watch

From your project folder, run geo guard setup. It shows the proposal, built from the rules you use, and asks the one question: watch (recommended) or not now. Guard checks each call your agents make to these tools against the rules. It also lists the rules it cannot cover, each with its reason. If you choose to watch, give --upstream: the address of the real tool, as host:port for plain HTTP or https://host for a service with a certificate that your computer trusts. You can add it later. Setup writes files only. Nothing starts yet.

geo guard start then starts Guard as its own program. While it watches, every call still goes through, and it records what it would have stopped. If Guard does not know where the tool runs yet, it cannot start, and says so.

geo guard setup                    # shows the proposal and asks the one question
geo guard setup --answer watch --upstream <host:port>
geo guard start
geo guard status

Without --answer, geo guard setup only shows the proposal. --answer watch applies it. To start Guard again after a crash with backoff, use geo guard start --supervise. On a Mac, geo guard login-item --confirm starts Guard, supervised, when you log in. Without --confirm it shows what it would write, and it is never loaded for you.

Point your agent at Guard

Change the address your agent uses for that tool so that it calls Guard instead of the tool. Each agent calls Guard with its own credential. geo guard agent-credential issues a new one, optionally expiring after some hours, and prints it once. Calls without a valid credential are refused, even while Guard only watches.

Read what it would have done

geo guard status shows what Guard is doing and the calls it has seen. geo prove incidents lists Guard calls that were stopped, held or would have been stopped. geo guard tools lists the tools Guard has pinned and any that changed.

Watching is also a record: Guard keeps what it would have done, and geo status says that Guard is on for the action. See What Guard does for each tool.

Decide to stop rule-breaking calls

When you have seen what Guard would have stopped and you are satisfied, switch Guard to stopping calls. Guard will refuse calls that break your rules and hold large ones until you approve them. Calls that reach your tools another way are not seen and are not stopped. If Guard cannot decide, it refuses the call unless you chose otherwise. You become the approver for that tool. Add others with geo guard approver-add. Restart Guard to apply the change.

geo guard promote --confirm-production
geo guard stop
geo guard start

The word “production” in the command is the name of Guard’s stopping mode. It does not mean that Guard is ready for production traffic. geo guard promote without --confirm-production does nothing.

Controls you can use at any time

• Stop all new calls (geo guard kill) and allow them again (geo guard kill --off). Anything already sent is not undone.

• Stop one agent’s new calls without stopping the others (geo guard agent-stop <agent>, with --off to allow them again).

• Accept or reject a tool whose definition changed (geo guard tool-review <name> --accept or --reject).

• Settle calls whose outcome is uncertain from the provider’s own records (geo guard reconcile). Nothing is sent again.

• Back up Guard’s store and evidence into a folder (geo guard backup --to <folder>).

• Approve or deny held calls (What to do when Guard holds a call.)

• What Guard does for each tool (How to read what Guard does with each action.)