Security model
This page describes Agentknock’s trust assumptions and implementation limits. For the introductory explanation, see Are my secrets safe?.
Trust boundaries
Section titled “Trust boundaries”| Component | Trust assumption |
|---|---|
| Phone | Android, the app, and its authorized users control credentials and approval decisions. Compromising the phone can expose values or authorize their use. |
| Client | Pairing identifies the client requesting access. A modified client can misrepresent the command and computer information shown for review. |
| Relay transport | The relay carries protected messages without their decryption keys. It can observe routing identifiers, sizes, timing, and connection information, and can delay or block exchanges. |
| AI review service | When the AI setting applies, the phone sends review context to the review service and model provider. Their decision can authorize access, so they are part of the authorization system. |
AI review is a separate data flow: the review service can read the context the phone submits, while client-phone exchanges remain encrypted.
Storage on the phone
Section titled “Storage on the phone”Environment values, SSH private keys, and protocol key material are encrypted before storage. Android Keystore protects the encryption keys, using secure hardware where available. The app’s authentication settings report the device’s actual protection.
For signing, the app decrypts the SSH private key into its own memory on the phone. The phone remains a trusted endpoint during use.
The authentication mode protects the interface and sensitive user actions. Background approval and signing follow the approval policy without requiring a fresh screen unlock for every storage-key use.
Android backups can include metadata, history, and encrypted records, but exclude the installation’s encryption keys. Restoring a backup does not recover secret values. See Delete your data for details.
Pairing and message protection
Section titled “Pairing and message protection”The pairing address starts a pairing attempt. Comparing the complete verification code on the computer and phone authenticates the intended pairing. The address alone does not authenticate the initial exchange.
After verified pairing, requests and responses are encrypted and authenticated. Altered contents fail authentication; retained exchange state prevents repeated processing of accepted messages. The cryptosystem specification defines the algorithms, verification-code strength, and replay handling.
Compromise and past exchanges
Section titled “Compromise and past exchanges”The CLI stores pairing credentials locally. A stolen current pairing key allows client impersonation, but that key alone cannot decrypt previously recorded exchanges. Live exchange state or delivered plaintext can be exposed by a compromise during use.
A later compromise of the phone’s long-term protocol private key has wider consequences. With the recorded initial pairing and subsequent exchanges, an attacker can reconstruct keys and decrypt past traffic. Agentknock v1 does not provide forward secrecy against this device-key compromise.
Routine pairing-key rotation does not recover a known-compromised client relationship. Suspend or revoke that client on the phone.
What the client receives
Section titled “What the client receives”| Use | Data flow |
|---|---|
| Environment or standard-input delivery | The requested values. The command, its descendants, and other processes with sufficient access can read, copy, store, or transmit them. Agentknock does not save them in its own pairing file. |
| SSH authentication or Git signing | The public key and approved signature, while the private key stays on the phone. Each authentication or signature receives its own device decision under the applicable policy. |
| Secret upload | Data travels from the client to the phone and becomes active only after acceptance there. Uploading leaves the source copy on the computer. |
An SSH approval authorizes authentication. The destination server controls what the resulting session can do.
Command context and execution
Section titled “Command context and execution”The client reports the command, arguments, working directory, executable details, launch context, selected secrets, and optional reason. These support review but are not remote attestation of the computer or a guarantee of the program’s behavior.
The CLI selects and opens the executable before approval, then revalidates it before launch. On Linux, native binaries execute through the retained file descriptor; scripts execute by pathname. On macOS, both use the captured pathname. Path-based execution leaves a race after the final check, and even a retained file’s contents can change.
These checks do not pin interpreters, libraries, plugins, configuration files, or descendant commands. Agentknock is not a sandbox: the command keeps its operating-system privileges and filesystem and network access. The command execution design explains the platform-specific checks.
Approval scope
Section titled “Approval scope”Approval protects sensitive-value delivery and private-key operations. Metadata, SSH public keys, and environment values marked non-sensitive can be provided without approval.
Allow once covers the current request. Temporary access covers a client, secret, operation type, and expiry; later commands within that scope may proceed. The Allow setting automatically permits valid requests under the applicable settings.
The AI setting asks a model to approve, deny, or ask you to decide. The model can make a mistaken decision. Review context includes instructions, command information, non-sensitive environment values, and signing information. Sensitive stored values and private keys are omitted. A credential included in arguments, reasons, instructions, or captured script source is still exposed as review context.
An approval releases values or permits signing; it does not enforce every action the client takes afterward. Revoking a client stops future access through that relationship but cannot invalidate a copied credential. Revoke or rotate that credential at the service that accepts it.
Source and release verification
Section titled “Source and release verification”The CLI source and Android source are public. Each repository maintains its verification procedure:
- CLI release verification covers build attestations and independent reproduction of release archives.
- Android APK verification covers APK signatures, the published app-signing certificate, checksums, and GitHub attestations from the release signing workflow.
An attestation binds the exact file being checked to its recorded source commit and workflow. A check of a GitHub artifact does not verify a different APK delivered by Google Play. Neither attestations nor reproducible-build checks prove the source or dependencies are free of vulnerabilities.
Related guidance
Section titled “Related guidance”- Delete your data covers device deletion, backups, and relay retention.
- Report a security issue provides private reporting channels.