Documentation
Stepwise Secret & PII Scanner for Jira: user guide
Everything the app does, in the order you will meet it: the rules, what is checked, masking, the create check, alerts, the history scan and the details admins ask about.
On this page
Getting started
Stepwise Secret & PII Scanner for Jira is a Jira Cloud app. A Jira admin installs it from the Atlassian Marketplace and approves its permissions (they are explained under Permissions). It works with Jira Service Management requests too. It is a separate app from Stepwise Secret & PII Scanner for Confluence.
Open the scanner
- Open Jira settings, then Apps, then Stepwise Scanner. You need to be a Jira admin.
- The Overview shows open findings by kind, what has been masked, removed or dismissed, and Insights.
- Press Scan existing content to check everything that is already in Jira. See Scan your history.
From then on, work items and comments are checked when they are created or edited. Space admins see their own space under Space settings, Sensitive data.
Rules and kinds of data
The Rules tab lists every detector by category. Each can be switched on or off. The app has 42 built-in detectors: pattern matching plus a check where one exists (a checksum, a length, a context). There is no AI and no outside service.
| Detector | Category | Severity | Default |
|---|---|---|---|
| AWS access key, AWS secret key | Secrets | High | On |
| Google API key, Google OAuth client secret | Secrets | High | On |
| Azure storage key, Azure SAS token, Azure client secret | Secrets | High | On |
| GitHub token, GitLab token, Slack token, Slack webhook | Secrets | High | On |
| Stripe live key | Secrets | High | On |
| Stripe test key | Secrets | Low | Off |
| Atlassian, OpenAI, Anthropic, npm, PyPI, SendGrid, Shopify, DigitalOcean, Hugging Face, Docker, Telegram, Postman, Linear, Notion, Figma and Vault tokens | Secrets | High | On |
| Private key (RSA, EC, OpenSSH, PKCS#8, PGP) | Secrets | High | On |
| JSON Web Token | Secrets | Medium | On |
Password written as password: …, in links, configs and sentences, in 20 languages | Secrets | High | On |
Secret in a config line (api_key = …, client_secret: …) | Secrets | High | On |
Credentials in a link (user:password@host) | Secrets | High | On |
| Authorization header (Bearer, Basic) | Secrets | High | On |
| Card number (Luhn-checked) | Financial data | High | On |
| IBAN (checksum for its country) | Financial data | Medium | On |
| US Social Security number | Personal data | High | On |
| Email address | Personal data | Low | Off |
| Phone number | Personal data | Low | Off |
| UK National Insurance number | Personal data | Medium | Off |
| Spanish DNI / NIE | Personal data | Medium | Off |
A match covers only the secret part. For password=hunter2x it is the value, not the word password. When matches of two detectors overlap, the more specific one is kept.
What is not a finding
- Placeholders:
<password>,{{token}},${SECRET},%PASS%,$VAR,***,xxxx,REDACTED,null,none. - References to a vault or an environment:
vault:,env:,process.env.. - Sentences such as “my password is expired”: a spoken password has to look like a password.
- Well-known test data, while Ignore well-known test data is on (the default): documentation keys such as AWS
…EXAMPLE, test card numbers, example IBANs and SSNs.
Ignore values and exclude spaces
- Ignore values containing: up to 50 values of up to 100 characters, for example
example.comor a test key prefix. Case does not matter. - Excluded spaces: up to 200. Nothing in them is checked.
- Dismiss a finding with a reason: Not sensitive, Test data or Accepted risk. It stays dismissed while the match keeps its length. A different length opens it again.
What is checked, and when
- Summary and description of a work item.
- Comments, including JSM customer comments and internal notes.
- Text fields: single-line and multi-line custom fields (up to 30 fields).
The app checks a work item or comment when Jira reports that it was created or changed. A check is not instant: Jira delivers the event to the app after a short delay, so an email notification from Jira can arrive before the scanner has looked. A request raised in the Jira Service Management customer portal comes without a "created" event, so the app also looks at new work items every five minutes: such a request is checked within about five minutes. Use the create check to hold a work item before it exists.
Life of a finding
- Open
- A match is in the text now.
- Masked
- The value in a comment was replaced by a label.
- Removed
- The value is gone: someone edited it out, the comment or work item was deleted, or an admin marked it.
- Dismissed
- A person decided it is not a problem.
Checking the same text again changes nothing. If a value comes back after it was removed, the finding opens again.
Findings and Preview
The Findings tab lists findings with filters for space, state, category and kind. Each row shows the kind, the work item and field, when it was found and its state.
- Preview reads the text as you, finds the match and shows about 40 characters around it with every found value hidden. For cards and SSNs you see the last four digits; for tokens with a public prefix, the prefix. Nothing is saved.
- Mask (comments), Dismiss, Reopen and Mark resolved act on the finding.
Masking comments
Masking is off by default. A Jira admin turns it on in Rules and picks the categories: secrets and financial data by default, personal data if you choose.
- The scanner reads the comment again, finds the values in the fresh text and builds the new text: each value becomes
***REDACTED: AWS key***(or the label of its kind). - It checks before it writes: the new text must equal the old text with the labels in place of the values, nothing else in the comment may change, and a second scan of the new text must find nothing to mask. If a check fails, the comment is left as it is and the journal records Masking failed.
- It saves only that comment, with the same visibility (public or internal) as before.
- If the app is not allowed to edit that comment, the finding stays open with a note.
The Mask button on a finding does the same as you, with your permissions.
What is not masked
Descriptions and summaries are not rewritten. Jira keeps the earlier text in the work item History, so editing does not remove it. The finding says what to do: remove the value, and if it is a credential, rotate it. To get rid of it in History, clone the work item without the value and delete the original, as Atlassian advises.
A secret that was seen or emailed before it was masked has been exposed. Rotate real credentials every time.
Hold a create with the workflow validator
The app adds a validator to Jira’s workflow editors: Stepwise: no secrets in the text. It sits on a transition and stops it while the text holds a secret. The most useful place is the Create transition: the work item is not created until the secret is removed.
Add the validator
- Open the workflow of the work type you want to cover, in Jira’s workflow editor.
- Select the Create transition (or any other).
- Open the transition’s validators and choose to add one.
- Pick Stepwise: no secrets in the text.
- Publish or save the workflow.
Jira renames buttons in its workflow editors from time to time. The order stays the same: workflow, transition, add a validator, pick the Stepwise validator, publish.
What holds a transition
| Setting | What holds the transition |
|---|---|
| Secrets (default) | Credentials: keys, tokens, private keys, passwords |
| Secrets and financial data | The above, plus card numbers and IBANs |
| Everything the scanner finds | Every kind that is switched on, personal data too |
| Never block | Nothing: the check stays in the workflow but lets everything through |
The validator checks the description, text fields and the comment that come with the transition. A message looks like this: This text holds sensitive data (AWS access key). Remove it before you continue: once saved, it stays in the history and goes out in email notifications. Checked by Stepwise Scanner. It names the kind of data and never shows the value.
In Jira Service Management, a request raised in the customer portal goes through the same check when the validator sits on the request type’s create transition. The customer sees the message on the portal and can fix the text before sending again.
If the scanner itself fails, the transition passes and the journal records it. The check should never stop your team’s work because of a fault in the scanner.
Alerts
On the Alerts tab choose up to five Jira groups. When the scanner finds something new, it sends an email notification through Jira to those groups.
- Also email the author: the person who wrote the text gets one too (not portal customers).
- Threshold: only findings at or above this severity send mail. The default is High.
- At most one email per work item per hour.
- The email says what was found and where, for example “Sensitive data found in SUP-42”, and never contains the value.
- The history scan does not send email.
Scan your history
On the Overview, Scan existing content checks every space (except the ones you excluded): summaries, descriptions, text fields and every comment.
- It runs in the background in small chunks, so a large site is fine. Progress shows spaces, work items and findings so far.
- You can pause, resume or stop it. If it stalls, it restarts by itself within minutes.
- It waits when Jira asks it to slow down.
- Findings from the scan are listed like any other. The scan does not send email.
Insights and the space page
The Overview shows findings by space (top 10), by kind (top 10) and by week (last 8 weeks), and for JSM how many are in public comments and how many in internal notes. Space admins open Sensitive data in Space settings for the findings and Insights of their space. The rules there are read-only.
Journal and CSV
The Journal tab records what happened, where and when. It never holds the value.
- Found, reopened, removed, dismissed, masked, masking failed, email sent, create held.
- Scan started, finished or stopped, and settings changed.
- Who: only app or user, never a name or an account ID.
- Entries are kept for 13 months. Removed findings are kept for 180 days.
Permissions
Who can do what
| Action | Who |
|---|---|
| Open the scanner, change rules, alerts and masking | Jira admins |
| Run, pause or stop the history scan | Jira admins |
| See findings and Insights of a space | Space admins, in Space settings |
| Preview, Mask, Dismiss | Admins; Preview shows only what that person may see in Jira |
| Add the validator to a workflow | Whoever may edit that workflow in Jira |
What the app is allowed to do
When the app is installed, Jira asks the admin to approve four permissions:
| Permission | Why the app needs it |
|---|---|
read:jira-work | To read work items, comments and text fields for the checks, to run the history scan, and to ask Jira what the current person may see |
write:jira-work | To save a masked comment when masking is on, and to send the alert email |
read:jira-user | To search for groups when you pick alert recipients. Group names are shown, never stored |
storage:app | To keep settings, findings, the journal and the scan state in Atlassian-hosted app storage |
The app acts as itself, not as a person, where nobody is present to act: reading new text when Jira reports an event, the history scan, masking and alert emails. What you do on screen runs with your own permissions.
Limits
| Item | Limit |
|---|---|
| Detectors | 42 built-in |
| Custom patterns (Premium) | 20, up to 200 characters each |
| Values to ignore | 50, up to 100 characters each |
| Excluded spaces | 200 |
| Alert groups | 5 |
| Text checked per field | 2,000,000 characters (longer text is marked as checked partly) |
| Findings per kind in one field | 100 |
| Custom text fields checked | 30 |
| Emails per work item | 1 per hour |
Data and privacy
- Settings, findings, the journal and the scan state are stored in Atlassian-hosted app storage (Forge storage), separately for your site.
- A finding holds: the space, the work item, the field, the kind, severity, state, how long the match is, its line and column, when it was found and last seen, who changed its state (app or user) and, for JSM, whether the comment was public or internal.
- Not stored: the found value, a hash of it, any text around it, work item titles, names, emails and account IDs.
- Nothing is written to work items other than a masked comment when you turn masking on.
- Nothing is sent to any other server. There are no external services, no analytics and no AI. Data follows your Jira data residency.
- Alert emails go out through Jira. The author’s address is passed straight to Jira and is not saved.
More detail: Security and data. Legal wording: Privacy policy.
FAQ
- What does Stepwise Secret & PII Scanner for Jira find?
- AWS, Google Cloud and Azure keys; GitHub, GitLab, Slack, Stripe, Atlassian and OpenAI tokens; private keys; JWTs; passwords written in text and configs; credentials in links; card numbers (Luhn-checked); IBANs; and US Social Security numbers. Email addresses, phone numbers, UK NINO and Spanish DNI can be switched on. 42 built-in detectors in all.
- Does it work with Jira Service Management?
- Yes. Requests, customer comments and internal notes are checked, and each finding shows whether the comment was public or internal.
- Can it hide a secret?
- In comments, yes. Turn masking on and the app replaces the value with
***REDACTED: AWS key***and edits only that comment text. Summaries and descriptions are not rewritten: the finding tells you where the value is, and you remove it and rotate the key. - How quickly does it check?
- When Jira reports that a work item or comment was created or changed, the app checks it. To cover what already exists, run the one-off scan of your history from the Overview.
- Can it stop a work item from being created?
- Add the workflow validator “Stepwise: no secrets in the text” to the Create transition. While the text holds a secret, the transition does not pass and the message says what to remove. The docs walk through it.
- Who gets alerts?
- The Jira groups the admin chooses, and optionally the author of the text. The email says what was found and where, never the value.
- Does it store the secrets it finds?
- No. It stores where a finding is (work item, field, line and column), its kind and its state. It does not store the value, a hash of it or any text around it.
- How do I cut false alarms?
- Switch off kinds you do not need, keep “Ignore well-known test data” on, add values to ignore, exclude whole spaces, and dismiss a finding with a reason.
- Does it use AI?
- No. Detectors are patterns with checks such as a checksum, and everything runs inside Atlassian.
- Does it work with the Confluence version?
- They are separate apps. Each is installed on its own. See Stepwise Secret & PII Scanner for Confluence.
- Does it support dark theme?
- Yes, it follows each person’s Jira theme automatically.
Troubleshooting
- I do not see a finding I expected
- Check that the kind is switched on, that the space is not excluded, that the value is not on the ignore list, and that it is not a placeholder or well-known test data. Then press Scan existing content to cover older text.
- Too many findings from test data
- Keep “Ignore well-known test data” on, add the prefix of your test keys to the ignore list, or exclude the test space.
- Masking did not change a comment
- The app leaves a comment alone if a safety check fails, or if it is not allowed to edit it. The finding says why, and the journal shows Masking failed.
- A create was held and I do not know why
- Read the message: it names the kind of secret and where it is. Remove it and try again. If it is a placeholder, add it to the ignore list.
- No alert email arrived
- Check that a group is chosen on the Alerts tab, that the severity reaches the threshold, and the notification settings of your Jira site. Only one email per work item goes out each hour.
Not available yet
These are not in the app today. We list them so that you know what not to look for yet. There are no dates attached.
- Masking of descriptions and summaries (Jira keeps earlier text in History)
- Checking attachments
- Scheduled history scans
Missing something else? Tell us.