Security audit
Security checks for vulnerabilities and agentic risk
This is a coherent FreshBooks shell helper, but it gives broad live accounting write capability and exposes OAuth tokens in ways users should review carefully before installing.
Install only if you intend to let an agent or shell user access FreshBooks with the same authority as the OAuth app. Treat it as write-capable, not read-only: review commands before running POST or PUT examples, avoid using it against production data casually, and do not log or paste the printed OAuth tokens.
Code accesses credential files (SSH keys, AWS credentials, etc.). This could indicate credential theft attempts.
FreshBooks has a real REST API reachable server-side — no browser bridge, no signed-in
tab, no `fpx`. Authentication is **OAuth2 only**: there is no API key and no personal
access token, so a one-time browser authorize flow is unavoidable.
## The two things that break naive clients
Code accesses credential files (SSH keys, AWS credentials, etc.). This could indicate credential theft attempts.
FreshBooks has a real REST API reachable server-side — no browser bridge, no signed-in
tab, no `fpx`. Authentication is **OAuth2 only**: there is no API key and no personal
access token, so a one-time browser authorize flow is unavoidable.
## The two things that break naive clients
Referenced artifact was not completely inspected
`references/fb-token.sh`, which persists the rotation before returning, and never point
Referenced artifact was not completely inspected
`references/fb-token.sh`, which persists the rotation before returning, and never point
Code accesses credential files (SSH keys, AWS credentials, etc.). This could indicate credential theft attempts.
| `invalid_client` on refresh | The refresh grant needs `client_secret` **and** `redirect_uri`, form-encoded — not JSON |
| `invalid_grant` on refresh | The token was already spent. Re-run the bootstrap |
| 404 on a valid-looking record | Wrong identifier for that URL family — run `fb_ids` |
| 401 on every call | Access token stale and refresh failing; check the state file |
See `references/recipes.md` for ready-to-run request bodies and `jq` recipes.
The function echoes a valid access token to stdout, which increases the risk of accidental credential disclosure through shell history, command substitution, process tracing, logs, or downstream scripts printing values. In a helper specifically designed for scripting, this context makes exposure more plausible because callers may capture or display the token inadvertently.
chmod 600 "$FB_STATE"
}
# Echo a valid access token, refreshing (and persisting the rotation) when stale.
fb_access_token() {
fb_state_init || return 1
local now exp tok
The skill is described as a query tool, but this section documents invoice creation via POST, which can create live financial records. That mismatch increases the chance that a user or downstream agent will invoke destructive or state-changing actions under the false assumption that the skill is read-only.
These recipes include creating clients, recording payments, accepting estimates, and emailing estimates, all of which modify business state or trigger external actions. In a skill presented as query-oriented, such hidden write capability can lead to unauthorized billing changes, customer communications, or accounting integrity issues.
The skill clearly enables shell execution and outbound network/API access, but the manifest does not declare any tool scope or permission boundaries. This increases the chance an agent or user invokes it with broader capabilities than expected, including remote writes to FreshBooks, without an explicit trust or consent model.
Data is being sent to an external URL. This could be legitimate telemetry or data exfiltration. Manual review is recommended.
| jq '.response.result.invoices[] | {id, invoice_number, amount, outstanding, status}'
`fb_curl <path> [curl args…]` attaches the bearer token and `Api-Version: alpha`;
everything after the path is passed to `curl`, so writes work too.
## Response envelopes differ per family
The skill is described as a query tool, but the documentation states that arbitrary curl arguments are passed through and that writes work too. This is a capability mismatch that can mislead users or agents into invoking a skill believed to be read-only when it can modify external accounting data.
The skill documents a generic API wrapper that forwards curl arguments and supports writes, but it does not prominently warn that using it can modify remote FreshBooks records. Without an explicit warning or confirmation step, users may unintentionally perform destructive or compliance-sensitive actions against live accounting systems.
The later documentation provides explicit POST/write guidance, payload structure, delete semantics, and persistence caveats, confirming the skill is not merely query-focused. In an accounting context, hidden write capability is more dangerous because it can create, alter, or soft-delete financial records while appearing to be a read helper.
The manifest describes a shell skill for querying FreshBooks business data like invoices, clients, payments, and time tracking using curl with a rotating OAuth token. This file instead bootstraps OAuth credentials by generating authorization URLs, exchanging authorization codes, refreshing tokens, and calling the identity endpoint, which is broader than simple data querying and not reflected in the description.
The script prints access and refresh tokens in full to stdout, which can expose long-lived credentials to shell history capture, terminal logging, CI logs, process wrappers, or downstream pipes. In a shell-oriented skill, this is especially risky because stdout is commonly redirected or inspected by other tools, turning valid OAuth credentials into easily leaked secrets.
Commands invoke sudo or root privileges. Verify this elevated access is necessary and justified.
echo "fb: no state at $FB_STATE and FRESHBOOKS_REFRESH_TOKEN unset — run the bootstrap in SKILL.md" >&2
return 1
fi
mkdir -p "$(dirname "$FB_STATE")" && chmod 700 "$(dirname "$FB_STATE")"
printf '{"refresh_token":"%s","access_token":"","expires_at":0}\n' "$FRESHBOOKS_REFRESH_TOKEN" > "$FB_STATE"
chmod 600 "$FB_STATE"
}
Commands invoke sudo or root privileges. Verify this elevated access is necessary and justified.
fi
mkdir -p "$(dirname "$FB_STATE")" && chmod 700 "$(dirname "$FB_STATE")"
printf '{"refresh_token":"%s","access_token":"","expires_at":0}\n' "$FRESHBOOKS_REFRESH_TOKEN" > "$FB_STATE"
chmod 600 "$FB_STATE"
}
# Echo a valid access token, refreshing (and persisting the rotation) when stale.
Commands invoke sudo or root privileges. Verify this elevated access is necessary and justified.
fi
mkdir -p "$(dirname "$FB_STATE")" && chmod 700 "$(dirname "$FB_STATE")"
printf '{"refresh_token":"%s","access_token":"","expires_at":0}\n' "$FRESHBOOKS_REFRESH_TOKEN" > "$FB_STATE"
chmod 600 "$FB_STATE"
}
# Echo a valid access token, refreshing (and persisting the rotation) when stale.
Data is being sent to an external URL. This could be legitimate telemetry or data exfiltration. Manual review is recommended.
local rt resp new_rt new_at expires_in created_at
rt=$(jq -r '.refresh_token' "$FB_STATE")
resp=$(curl -sS -X POST https://api.freshbooks.com/auth/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode "client_id=$FRESHBOOKS_CLIENT_ID" \
--data-urlencode "client_secret=$FRESHBOOKS_CLIENT_SECRET" \
Data is being sent to an external URL. This could be legitimate telemetry or data exfiltration. Manual review is recommended.
local rt resp new_rt new_at expires_in created_at
rt=$(jq -r '.refresh_token' "$FB_STATE")
resp=$(curl -sS -X POST https://api.freshbooks.com/auth/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode "client_id=$FRESHBOOKS_CLIENT_ID" \
--data-urlencode "client_secret=$FRESHBOOKS_CLIENT_SECRET" \
Data is being sent to an external URL. This could be legitimate telemetry or data exfiltration. Manual review is recommended.
local rt resp new_rt new_at expires_in created_at
rt=$(jq -r '.refresh_token' "$FB_STATE")
resp=$(curl -sS -X POST https://api.freshbooks.com/auth/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode "client_id=$FRESHBOOKS_CLIENT_ID" \
--data-urlencode "client_secret=$FRESHBOOKS_CLIENT_SECRET" \
Data is being sent to an external URL. This could be legitimate telemetry or data exfiltration. Manual review is recommended.
printf '%s' "$new_at"
}
# curl against the FreshBooks API with auth attached. Args after the path are
# passed through to curl, so: fb_curl /path -X POST -d '{...}'
fb_curl() {
local path="$1"; shift
The examples instruct users to source ~/.secrets into the shell environment without any guidance on credential hygiene, least privilege, or avoiding accidental exposure through logs, child processes, or shell history. While common in shell workflows, undocumented secret-loading increases the risk of token leakage and unsafe operational practices.
The markdown presents multiple POST and PUT examples that create invoices, clients, payments, time entries, or trigger estimate actions without warning that they mutate live accounting and customer-facing data. This omission makes accidental execution more likely, especially by agents or users assuming examples are safe to run for inspection.
Data is being sent to an external URL. This could be legitimate telemetry or data exfiltration. Manual review is recommended.
Create (unverified) — money amounts are strings:
fb_curl "/accounting/account/$ACCT/invoices/invoices" -X POST \
-H 'Content-Type: application/json' -d '{
"invoice": {
"customerid": 123,
No suspicious patterns detected.