How the attack works
An attacker who uses a stolen password or a stolen personal access token usually does so from a network the owner never used. Finding that in a log normally needs a history of addresses per account, which a single-event rule cannot hold. GitLab makes that comparison itself and writes the result as two audit event types: user_signed_in_from_unseen_ip, described as a user signing in from a previously unseen IP address (GitLab 19.0 and later), and personal_access_token_used_from_unseen_ip, described as a personal access token being used from a previously unseen IP address (GitLab 19.1 and later).
The two events differ in where they can be read. The sign-in event is saved to the database, so it can also be read in GitLab's own audit event pages and API. The token event is marked as not saved to the database and reaches audit event streaming destinations only. GitLab's event type reference gives the one-line description of each event and nothing more: it does not say how many addresses are remembered per account or token, or for how long. The rules on this page therefore read the events as GitLab's own verdict and leave the comparison to GitLab.
What an attacker needs
- A password with no second factor, or a personal access token of a GitLab user, obtained through phishing, malware or a leak in a repository or a log.
- Log collection: audit event streaming (Ultimate) to an HTTP destination, received as JSON. Both events have the User scope, and the token event exists only in the stream.
Impact
The attacker has the access of the account or the token: the projects and groups it can reach, their source code and CI/CD configuration, and with the api scope the ability to change them. A sign-in also opens the way to new access tokens and SSH keys on the account, which are separate credentials and stay valid until they are revoked or expire.
Detection rules
GitLab Personal Access Token Used From a Previously Unseen IP Address
Detects the audit event type personal_access_token_used_from_unseen_ip, which GitLab describes as a personal access token being used from a previously unseen IP address (GitLab 19.1 and later, User scope). GitLab marks the event as not saved to the database, so it exists only in audit event streaming and cannot be read in the audit events of the instance. A token that was copied from a repository, a job log or a laptop is used from the attacker's network, and this event is the only single-event sign of it. The reference documents neither the fields of the event nor how the comparison works, so the rule matches on the event type.
title: GitLab Personal Access Token Used From a Previously Unseen IP Address
id: bf384042-2e0c-48d8-8dcb-a6919836bdea
status: experimental
description: >-
Detects the audit event type personal_access_token_used_from_unseen_ip,
which GitLab describes as a personal access token being used from a
previously unseen IP address (GitLab 19.1 and later, User scope). GitLab
marks the event as not saved to the database, so it exists only in audit
event streaming and cannot be read in the audit events of the instance.
A token that was copied from a repository, a job log or a laptop is used
from the attacker's network, and this event is the only single-event
sign of it. The reference documents neither the fields of the event nor
how the comparison works, so the rule matches on the event type.
references:
- https://docs.gitlab.com/user/compliance/audit_event_types/
- https://docs.gitlab.com/user/profile/personal_access_tokens/
- https://docs.gitlab.com/user/compliance/audit_event_streaming/
- https://attack.mitre.org/techniques/T1078/004/
author: Forestall
date: 2026-11-18
tags:
- attack.initial-access
- attack.t1078.004
logsource:
product: gitlab
service: audit
detection:
selection:
event_type: personal_access_token_used_from_unseen_ip
condition: selection
falsepositives:
- Tokens used by build systems and cloud runners whose outgoing address changes, and developers who move between networks. Add a filter on ip_address for the ranges of your own infrastructure.
- A token that was moved to a new server on purpose. Confirm with its owner.
level: medium
False positives
- Tokens used by build systems and cloud runners whose outgoing address changes, and developers who move between networks. Add a filter on ip_address for the ranges of your own infrastructure.
- A token that was moved to a new server on purpose. Confirm with its owner.
GitLab User Signed In From a Previously Unseen IP Address
Detects the audit event type user_signed_in_from_unseen_ip, which GitLab describes as a user signing in from a previously unseen IP address (GitLab 19.0 and later, User scope, saved to the database). GitLab holds the history of addresses and makes the comparison, and the rule reads the result. The reference does not document how the comparison works or how long an address is remembered, and it attaches no risk level. People change networks often, so this is a low-level signal that gains weight next to failed sign-ins, new credentials or bulk copying by the same account.
title: GitLab User Signed In From a Previously Unseen IP Address
id: 733e41bb-fc1b-4763-b44a-84dcb8f5d431
status: experimental
description: >-
Detects the audit event type user_signed_in_from_unseen_ip, which GitLab
describes as a user signing in from a previously unseen IP address
(GitLab 19.0 and later, User scope, saved to the database). GitLab holds
the history of addresses and makes the comparison, and the rule reads
the result. The reference does not document how the comparison works or
how long an address is remembered, and it attaches no risk level. People
change networks often, so this is a low-level signal that gains weight
next to failed sign-ins, new credentials or bulk copying by the same
account.
references:
- https://docs.gitlab.com/user/compliance/audit_event_types/
- https://docs.gitlab.com/user/compliance/audit_event_schema/
- https://attack.mitre.org/techniques/T1078/004/
author: Forestall
date: 2026-11-18
tags:
- attack.initial-access
- attack.t1078.004
logsource:
product: gitlab
service: audit
detection:
selection:
event_type: user_signed_in_from_unseen_ip
condition: selection
falsepositives:
- Users on a new home network, a phone hotspot, a journey or a VPN exit they had not used before. Add a filter on ip_address for the ranges of your offices and VPN, and keep the rule for administrators and group Owners.
level: low
False positives
- Users on a new home network, a phone hotspot, a journey or a VPN exit they had not used before. Add a filter on ip_address for the ranges of your offices and VPN, and keep the rule for administrators and group Owners.
Detection logic
Patterns that need more than one event, a baseline or knowledge of your own environment. Each is a hypothesis to build and tune in your SIEM, not a ready rule.
Unseen address followed by new credentials or changed sign-in details on the same account
A sign-in from a new address is ordinary. The same account receiving a new access token or SSH key, or a changed email address, password or second factor soon after is the pattern of a takeover in which the attacker makes the access durable before the owner notices.
- GitLab reports an unseen address:
user_signed_in_from_unseen_ip(GitLab 19.0 and later). Keep the account (entity_path), the address (ip_address) and the time. - In the following 24 hours, collect events of the same account:
personal_access_token_created,add_ssh_key,email_created,user_email_address_updated,user_password_updatedanduser_disable_two_factor. - Alert when at least one of them exists, and raise the priority when its
ip_addressis the unseen address.
Eventsuser_signed_in_from_unseen_ippersonal_access_token_createdadd_ssh_keyemail_createduser_email_address_updateduser_password_updateduser_disable_two_factor
LimitsA user who sets up a new laptop on a new network signs in from an unseen address and adds an SSH key on the same day. GitLab does not document per event type which field names the account, so confirm on one test event that the fields match between the two kinds of event. The 24 hours are a starting point.
Triage
- Read the account and the address of the event (
entity_path,author_name,ip_address), and place the address. A range that belongs to your offices, VPN or runners needs no further work. - Ask the user through a channel other than GitLab whether the sign-in or the token use was theirs, for example a new home network or a journey.
- For a token, find out which token was used. The personal access tokens page of the user shows the usage dates and the last five distinct connection IP addresses of each token.
- Review what the account did from that address afterwards, such as Git operations on many projects, new access tokens, new SSH keys, or a changed email address or password.
- Check for failed sign-ins for the same account before the event, which point to guessing instead of a stolen credential.
Response
Once the attack is confirmed:
- Revoke the personal access token that was used, or reset the password of the account and revoke its active sessions, as soon as the owner does not recognise the address.
- Delete the access tokens and SSH keys that were added to the account after the event, and undo changes to its email addresses and second factor.
- List the projects the account or the token read from that address and rotate the credentials stored in those repositories and their CI/CD variables.
- Find out how the credential leaked, for example a token committed to a repository or printed in a job log, and remove it there.
- Watch the account and the address for new sign-ins and token use over the following days.
Mitigation
- Enforce two-factor authentication, so that a stolen password alone does not complete a sign-in.
- Give personal access tokens a short expiry date and the narrowest scopes that work, and revoke tokens that are no longer used.
- Restrict access to top-level groups by IP address where your users and runners work from known ranges.
- Keep the email notification for unknown sign-ins turned on, so that the user hears about the sign-in as well.
- Stream audit events to your SIEM, because the token event is not saved to the database.
Frequently asked questions
How does GitLab decide that an IP address is unseen?
The event type reference describes the two events in one line each and does not document the comparison, the number of addresses remembered or the retention. GitLab's documentation of two related features gives an idea of the data it holds. The email notification for unknown sign-ins checks the last sign-in address, the active sessions and a cookie, and the personal access tokens page shows the last five distinct connection addresses of a token. Do not assume that the audit events use the same logic.
Can I read the token event in the audit events page of GitLab?
No. GitLab marks `personal_access_token_used_from_unseen_ip` as not saved to the database, so it reaches audit event streaming destinations only. The sign-in event `user_signed_in_from_unseen_ip` is saved and can also be read in GitLab. Streaming audit events to external destinations needs the Ultimate tier.
Why is the sign-in rule only a low-level signal?
People change networks all the time. A new home connection, a phone hotspot or a hotel produces the same event as a stolen password, and GitLab does not attach a risk level to it. The event is most useful as context: next to failed sign-ins, a new access token, a new SSH key or copies of many projects from the same account, it turns a routine alert into a likely takeover.
Does a top-level group stream carry these events?
GitLab gives both event types the User scope, not the Group scope. The reference says that the scope limits where an event type is available, but it does not spell out which stream carries events of the User scope. Check with a test sign-in from a new address whether your group destination receives the event, and use the instance stream where you can.
References
- MITRE ATT&CK T1078.004: Valid Accounts, Cloud Accounts
- GitLab Docs: Audit event types
- GitLab Docs: Audit event schema and examples
- GitLab Docs: Notification emails (notifications for unknown sign-ins)
- GitLab Docs: Personal access tokens (view token usage information)
- GitLab Docs: Group access and permissions (restrict group access by IP address)
- GitLab Docs: Audit event streaming for top-level groups