Gameheim

Gameheim Perforce extension: security and IT review

For the Perforce administrator and the security team who must approve the Gameheim extension before it goes on a production server. Every request it sends, every command it runs, every counter and file it writes, the network it needs, where Gameheim keeps the data and how to check the package you install.

By Gianmarco Virzì, co-founder and lead developer of Virsion · Updated · 15 min read

Code on the commit server needs a review before it is installed

The commit server holds the whole history of the project, often for games that are not announced yet. Anything installed there goes through a change review, and the people who approve it ask the same questions every time:

  • What runs inside the server, as which user, and with which permissions?
  • What does it change on the server?
  • What leaves the server, to which address, and how is it protected on the way?
  • Where is that data kept, and for how long?
  • What does it cost the server, and what happens when the other side is down?
  • How do we know the package we install is the one we reviewed, and how do we take it out?

This page answers them in that order. The installation itself is in Install the Gameheim Perforce extension.

What the Gameheim extension runs on your Perforce server

The extension is a Perforce server extension: one Lua file (main.lua) in a package signed by Gameheim, which the server installs, runs and replicates itself. It reads as a service user you choose, named in its configuration (ExtP4USER), with review access on the project's depot paths. The server signs the extension in as that user by itself: the password is not written in any file.

Perforce commands it runs, as the service user

  • Changelists and files: describe -s, files -m, sizes -s, changes, client -o.
  • Protected paths (from version 1.3.0), only on projects with an active rule: fstat -Ol on the files of a changelist being submitted under the project's paths, and on a shelved changelist Gameheim asks it to fingerprint (fstat -Ol -Rs -e <change> <path>@=<change>); groups -i -u <user> only when a rule exempts a Perforce group.
  • Its own counters and keys: counter, counters -e, key, keys -e.
  • Context for the checks it makes: info, protects -m, protects -a, groups, users, user -o.
  • Only when you give the service user super (see the super option below): protects -M -u|-g for the people Gameheim lists.
  • On an SSL server, on its own connection to the server only: trust -i <fingerprint> or trust -y (see Trust of the server's own certificate below). Never trust -f.
  • P4 Code Review (from version 1.3.0, only for projects linked to Code Review): login -s on a connection of its own, with the service user and the ticket a super user gave it, to check that the ticket still works. In the background task, for the folders of the rules Gameheim asks about: depots and dirs <parent>/*, one level at a time, to read the folder names with the real case of the depot, which Code Review needs for its branch paths.

Three commands of the extension concern P4 Code Review, and any user can run them with p4 extension --run gameheim: cr-key prints the public half of the extension's own X25519 key; cr-connect <envelope> keeps a Code Review ticket only from an envelope sealed for that key, carrying the one-time value Gameheim gave to that project in the last ten minutes, and only after checking the ticket on the server; cr-disconnect <project> forgets a project's link only once its ticket no longer works.

It never changes files, changelists, users, groups or the protections table. With a protected path in Block mode it refuses a submit that has no approval, which is the point of that mode; it never changes the submit. For a project linked to P4 Code Review it calls your Code Review server (see the network section below). Outside Perforce it starts one process: a POSIX shell on Linux, and %SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe on Windows, to create its private files with owner-only access and, on Windows, to read random bytes for its key.

What it writes on the server

WhereNameWhat it holds
Countersgameheim-feed.<id>, one per projectThe last changelist sent to that project. The id is a fingerprint of the activation code, never the code: any user can read counters.
Countersgameheim-feed-owner, gameheim-feed-config, gameheim-feed-heartbeat, gameheim-ws-groupsWhich task is sending, a fingerprint of its configuration, when it last ran, a fingerprint of the group memberships.
Counters (super option only)gameheim-vis.<id>, gameheim-vis-redo.<id>How far the visibility computation got.
Keysgameheim-global-seq, gameheim-ws.<ServerID>.*, gameheim-ws-alive.<ServerID>A sequence number for commands that concern every workspace; on edges, workspace events waiting to reach the commit server (deleted once sent) and when the edge task last ran.
Files in the extension's data foldergameheim-keysOne line per project with the signing secret it agreed with Gameheim. Created with owner-only access (umask 077 on Linux, an access list for the server account on Windows).
Files in the extension's data folderlast-ping, edited-changes, workspace-events, groups-checked, last-events, ws-*, run-*, marker-epochTimestamps, changelist numbers to send again, and the names of workspaces that ran a sync-type command.
Files in the extension's data folder (protected paths)protected-<id> per project, protected-verdicts, protected-c-<number>The project's protected folders and their windows, the Perforce users who pass without approval, and the approvals as a SHA-256 of the approved file list with an expiry; the outcome of each checked submit (number, Perforce user, outcome) until it is sent. Never file content.
Files in the extension's data folder (P4 Code Review)cr-key, cr-link-<id> per linked project, cr-nonce-<id>, cr-out-<id>The private half of the extension's X25519 key; the project's Code Review link (service user, ticket, Code Review address, SHA-256 of its server's public key); the one-time value of a link being made, for ten minutes at most; what the last cycle found in Code Review until it is sent (review numbers, outcomes, the Perforce users who voted). The first three are created with owner-only access. Never sent to Gameheim: the ticket stays on your server.
Files in the extension's data folder (SSL servers)p4trust, trust-state, last-errorThe trust file of the task's own connection to the server (one line: the server's address and certificate fingerprint), why the task stopped if it did, and the first line of its last error, with depot paths cut.
Server logThrough the Perforce server logProject position, changelist numbers and error text. Never activation codes or secrets.

How to review the Gameheim extension before installing it

A review takes a test server, the package and about an hour. Nothing below needs a Gameheim account except the last step.

Before you start
  • A Perforce server you can experiment on, with a super user.
  • The package, from /downloads/perforce-extension/gameheim.p4-extension on www.gameheim.com, or from the Gameheim trigger tab.
  1. Check that the package is the published one

    Compute the SHA-256 of the package and compare it with the published value. For version 1.3.0 it is 00d2dece0c586f8d95fc75688538d54d8d89c9a4a91501809896e70f8af4acaf.

    Linux / Windows
    sha256sum gameheim.p4-extension
    Get-FileHash gameheim.p4-extension -Algorithm SHA256
  2. Read the code

    The package is a ZIP file. Inside are main.lua (the whole extension, as plain text), manifest.json, THIRD_PARTY_NOTICES.txt, the certificate and the signatures. The comment at the top of main.lua describes each job the extension does.

  3. Check the certificate before trusting it

    p4 extension --install gameheim-certificate.txt --cert shows the certificate's fingerprint without installing it. The Gameheim certificate is D1:D3:0C:CC:96:3E:7A:02:6F:C4:1C:16:C4:B2:21:84:35:15:66:C7. Trust it with --yes only if they match: from then on the server installs only packages signed with it.

  4. Install on the test server and watch it

    Follow the installation guide on the test server. Watch the outbound traffic (one address, below), the counters and keys listed above with p4 counters -e "gameheim-*" and p4 keys -e "gameheim-*", and the server log.

  5. Decide on the super option

    With review access only, the extension does not compute who sees which changelist; each person's Gameheim agent does it with their own Perforce user. Giving the service user super moves that work to the server and sends Perforce user names to Gameheim (see below). It is a choice, not a requirement.

What leaves your Perforce server

Every request is an HTTPS POST to https://www.gameheim.com/api/vcs-ingest/<action>. The address is written in the signed code, so changing the configuration cannot point the extension elsewhere.

RequestWhenWhat it carries
activateOnce per project, at installationThe activation code, the extension's public key (X25519), a nonce.
changesFor each changelist that touches the project's depot paths, and again when its description or type is editedNumber, author (Perforce user), time, description (up to 40 000 bytes), stream, whether it is restricted, how many files, and action, type and depot path of up to 501 files under the project's paths. Never file content.
pingEvery 10 minutesExtension version, the project's depot paths, whether the server is Unicode, and a 24-character fingerprint of the proxy and CA settings (never the settings themselves).
presenceWhen Gameheim asks, at most 50 numbersWhether each changelist number still exists.
workspacesEvery 5 minutesNothing: Gameheim answers with the names of the workspaces it knows for the project.
workspace-eventsAfter commands that change what a workspace has synced, and once a minute as a sign of lifeCommand name (such as sync), its time and the workspace name, only for workspaces Gameheim already knows for the project; commands that concern every workspace (protect, group, obliterate -y) without names; the ServerID of each server and when it last ran. Never file names or arguments.
protectionEvery minute by default, and within seconds while an approval request is open (Gameheim sets the pace)For the shelved changelists Gameheim asks about: path, action, file type, digest and size of each file under the project's paths (the fingerprint the approvers approve). Which approvals the extension holds. The outcome of each checked submit: changelist number, Perforce user, and whether it passed with an approval, without approval, through the bypass list or an exemption, or because the check failed. Never file content. Gameheim answers with the project's rules, bypass list and approvals.
identityWhen the Gameheim agent of a person asks the server to confirm who they areThe one-time code the agent presented, the Perforce user the server authenticated, whether that user has a password, the authentication method.

The super option: who sees which changelist

Only when the service user has super. Every 5 minutes the extension asks Gameheim for the Perforce users whose link to a Gameheim account this server confirmed, at most 1000, and for the groups or users a Perforce administrator chose to "see as" for members without a Perforce user. For each changelist it then sends, with visibility, the changelist's depot paths in the project and, for each of those users or references, which of the files they can see according to p4 protects -M. So this option sends Perforce user names; group names travel only from Gameheim to the server.

How the traffic is protected

  • TLS with certificate verification left on: the extension never disables it. It uses CaFile when set, otherwise the CA bundle of the machine; on Windows, the system certificate store.
  • Every request after the activation is signed with HMAC-SHA256 over the action, a timestamp, a nonce and the SHA-256 of the body, with a secret agreed through X25519 at activation. Gameheim refuses old timestamps and repeated nonces.
  • Every answer from Gameheim is signed too. An answer without a valid signature is ignored and the request is tried again later, so a proxy or a device in the middle cannot make the extension act on a forged answer.
  • Redirects are not followed. Connection timeout 5 seconds, request timeout 15 seconds, answers capped at 4 MB.

Trust of the server's own SSL certificate

The background task connects to the server it runs on, through the connection p4d hands it, as the operating system account of p4d: ssl:127.0.0.1:<port>, or the server's own address when p4d listens on one. That account has usually never trusted the server's certificate, so from version 1.2.3 the extension keeps a trust file of its own, p4trust in its data folder, for that connection only. It never writes the account's ~/.p4trust, and Perforce commands run by people keep their own trust.

  • Installed from Gameheim: the wizard reads the server's certificate fingerprint on the administrator's agent connection, which already trusts the server, and writes it in the global configuration (ServerFingerprint). The task trusts only that fingerprint (p4 trust -i): a server presenting another certificate is refused.
  • Installed with the script (ServerFingerprint is -): the task trusts the certificate at its first connection (p4 trust -y), and never a changed one.
  • When the certificate changes (usually a renewal), the task stops and the connection test says why, with the new fingerprint. Running the installation again from Gameheim writes the new fingerprint and the task starts again. The extension never uses p4 trust -f.
  • Each change of trust is written in the extension's log with the fingerprint.

The P4 Code Review ticket

With the Code Review engine of protected paths, the extension moves the review to approved or needs revision in Code Review and reads the votes. It does so as its service user, with a Perforce ticket of that user.

  • Only a Perforce super user can issue it, from their own agent, with p4 login -a -p and no password: an admin who is not super cannot. Gameheim also asks that the person holds both the approve and the bypass permission on the project.
  • The agent seals it for the extension (X25519, HKDF-SHA256 and HMAC-SHA256) and hands it over with cr-connect. Gameheim never receives it, and the Perforce server log only shows the sealed text.
  • By default it does not expire (Timeout: unlimited on a group of its own, as Perforce recommends for Code Review), or it lasts 30 or 90 days, as the studio chooses. Gameheim never changes the password of a user you chose.
  • Whoever can read the extension's data folder, or a backup of the server root, gets a ticket that works until it is revoked, with the service user's access: reading the paths it sees, and being the moderator in Code Review. It cannot let a submit through a protected path: the extension decides that, not Code Review.
  • To revoke it: "Disconnect" in Gameheim, or p4 logout -a <user> as a super user. A password change of that user revokes it too.

Network: what to allow

The commit server needs outbound HTTPS to www.gameheim.com, allowed by host name or with the Azure service tag AzureFrontDoor.Frontend. A server without direct internet access can go through a proxy set in HttpsProxy. Nothing connects to your server from outside: there is no inbound port to open. Edge servers need no internet access at all: they hand their workspace events to the commit server as Perforce keys.

With a project linked to P4 Code Review, the commit server also calls your Code Review server, inside your network, at the address a super user confirmed in Gameheim. Over HTTPS it talks only to the server holding the public key the super user confirmed: another server receives nothing, not even the request. It never follows a redirect and never uses the proxy.

Where Gameheim keeps the data

  • Changelist descriptions and file paths are encrypted at rest with AES-256/GCM under a key of your organization. Author, stream, counts, restricted flag, file action and type are stored as plain values, so Gameheim can filter and count them.
  • Gameheim runs on Microsoft Azure in Europe; the list of regions per service is in the sub-processors annex.
  • Changelists stay as long as the project exists. Deleting the project deletes its changelists, files, folders and keys. A changelist deleted in Perforce is marked as missing in Gameheim, not removed.
  • Only the members of the project who can read changelists see them, and with the super option or the agents, only the changelists and files Perforce lets each of them see.

Load on the server and what happens when Gameheim is down

Nothing waits for the network during a user's command. On a submit or a push the extension checks protected paths only when a project has an active rule: it reads the changelist's files under the project's paths with fstat -Ol and compares them with what it holds. In our tests on p4d 2025.1 and 2026.1 a changelist of 5,000 binary files (about 2 GB) and one of a single 1 GB file took the same time to submit with and without the check, within one second, because the server computes the digests while the files arrive. Without an active rule it only reads its own files. Any error inside the check lets the submit through, and Gameheim shows that submit. After sync-type commands and after editing a submitted changelist the extension only notes a name or a number in a file of its data folder. A background task (p4 bgtask -t gameheim, every 10 seconds) does the reading and the sending.

When Gameheim cannot be reached, the changelists wait in Perforce: a project's counter moves only after Gameheim has stored the changelist, and they leave in order once it answers again. Protected paths keep the last rules received: in Block mode only the bypass list, the exemptions and the approvals already received pass until Gameheim answers, and approvals and windows expire on time. To switch the check off at once, set ExtEnabled: false on the extension's instance. More on the queries Gameheim makes on large servers is in Large servers and edge servers.

Using Gameheim without the extension

The extension is optional. Without it, one Gameheim agent of the project reads the newest changelists every two minutes with its own Perforce user, so the history still reaches Gameheim. What the extension adds: changelists within seconds, including those submitted by build machines and from any tool; a synced-changelist value that costs one query per sync instead of one per minute on large workspaces; and the server's confirmation of who each person is. A studio can start without it and install it after its review.

Taking the extension out

Removing it takes a dozen commands as a super user: unset the startup command, stop the task, delete the extension, its counters and its keys. They are listed in Remove the extension. The changelists already in Gameheim stay with the project until it is deleted.

Frequently asked questions

Does the extension send the content of our files?

No. It sends changelist metadata: number, author, time, description, stream and the action, type and depot path of the files under the project's paths. File content never leaves the server.

Can the extension stop a submit?

Only for protected paths in Block mode, which the studio sets per folder in Gameheim: a submit there needs an approval, and the Perforce message tells the user how to ask for it. Flag mode lets every submit through and marks it. An error of the check never stops a submit.

Can someone change the address the extension talks to?

No. https://www.gameheim.com is written in the signed code. The configuration can set a proxy and a CA bundle, and a change to either is reported to the Perforce administrators of the project.

Does the service user need super?

No. review on the project's depot paths is enough for the feed. super only enables the optional visibility computation on the server, which sends Perforce user names to Gameheim.

Where is the password of the service user?

Nowhere outside Perforce. The server signs the extension in as that user by itself, so the password is not in any file on the server and Gameheim never sees it.

Does the extension change the trust of the p4d account?

No. It keeps its own trust file in its data folder, used only by its background task's connection to the server it runs on, and never accepts a changed certificate by force: after a renewal the installation is run again from Gameheim.

Can we read the code before installing it?

Yes. The package is a ZIP file and main.lua inside is plain text. Compare the SHA-256 of the package and the certificate fingerprint with the ones on this page before installing.