-
Notifications
You must be signed in to change notification settings - Fork 0
Quarantine and Severity
Not every bad file is bad in the same way. An .exe inside a TV download is unambiguously malicious; a .rar is how a large share of legitimate releases ship. Treating both as equally deserving of deletion is what makes automatic remediation feel risky.
Severity grades each finding. Quarantine gives the middle ground a place to go.
Before any of the grading below matters, there is one coarser control: how far Inspectarr is allowed to act at all. Set it in Settings → Rules, at the top of Remediation & Severity, or directly:
remediation:
operating_mode: automatic # monitor | quarantine | automatic| Mode | What happens |
|---|---|
| Monitor | Findings are inspected, graded and recorded. Nothing is paused, blocklisted or deleted. Use it to watch what your rules would do before letting them do it. |
| Quarantine | Nothing is deleted automatically — including by a quarantine timeout. Anything that would have been remediated is paused and held on the Quarantine review page instead. You can still delete deliberately from that page; the mode caps automatic action, not your decisions. |
| Automatic | The thresholds below are applied exactly as written. This is the default. |
Whenever the mode is not Automatic, a banner appears on every page. That is deliberate: an installation that has been told to hold back should never be mistaken for one that is actively protecting you, because that mistake is silent — you only discover it when something you expected to be gone is still sitting in your library.
The mode does not rewrite min_severity or remediate_at. Both keep the
values you gave them, so switching to Monitor and back is lossless.
It can only ever reduce an outcome, never escalate one. No mode can turn a release that was merely being recorded into one that gets deleted.
That matters for reading your own config later. A preset that quietly set
remediate_at: CRITICAL when you picked "Monitor" would leave the file
describing something you never chose. Keeping the two separate means both
readings stay true at once, which is why the settings page can tell you
precisely what will happen — "thresholds say DELETE, mode caps at record" —
rather than just showing you a dropdown and hoping.
The mode is a ceiling on automatic action. It applies to:
- a scan deciding to delete something
- a quarantine timeout firing
- the retry queue re-attempting a delete that failed earlier
It deliberately does not apply to the Delete button on the Quarantine page. Deciding is the entire purpose of a review queue, and a mode that blocked it would leave you with a queue you could not empty.
If a timeout would delete while the mode forbids it, the hold is kept and its timer is cleared, so it waits for you rather than firing again every scan. In Monitor mode the hold is released instead, since Monitor does not hold things at all.
They do the same thing. --dry-run is the per-run version:
python3 inspectarr.py --dry-runThe flag takes precedence over the configured mode, so a dry run on a box set to Monitor still behaves like a dry run and still sends the dry-run notification.
Two different reasons a torrent was not acted on, logged as two different events, because sending you to the wrong setting is worse than saying nothing:
| Event | Meaning |
|---|---|
below_severity_floor |
The thresholds said record. Change min_severity. |
capped_by_operating_mode |
The thresholds said more; the mode refused. Change operating_mode. |
The second carries both decision_before_mode and decision, so you can see
what would have happened in Automatic. The same is recorded on the inspection
row in operating_mode and action_detail.
Every condition that fires produces a finding, and each finding is graded independently. A single file can produce more than one — keygen.exe trips both bad_extensions and a bad_filename_patterns match, and each is graded on its own.
| Finding | Severity |
|---|---|
Executable or script extension (.exe .bat .msi .js .vbs .dmg .scr .lnk .jar …) |
CRITICAL |
Archive extension (.zip .rar .7z .iso .cab …) |
HIGH |
Primary file below min_file_size_mb
|
HIGH |
| Filename pattern match | MEDIUM |
| Any other flagged extension | MEDIUM |
A torrent's overall risk is the maximum of its findings, never an average. One executable among twenty routine findings is still an executable — averaging would bury it.
A risk_score (0–100) is also recorded, but it exists for display and sorting only. The level is what decides the outcome; the score can never promote a finding into a higher band.
If an extension is normal in your library, reclassify it. Extension keys win over signal keys.
remediation:
severity_overrides:
".rar": LOW # RAR is routine here
".iso": CRITICAL # but a disc image never is
"bad_filename_pattern": LOW # trust your own patterns lessEdit these in Settings → Rules → Raw YAML; the pane exposes the thresholds but not the override map.
Two thresholds split severity into three outcomes.
risk < min_severity -> recorded only, no action
min_severity <= risk < remediate_at -> QUARANTINED (paused, held)
risk >= remediate_at -> blocklisted and deleted
Both default to LOW, which collapses the quarantine band to nothing: everything flagged is deleted immediately. That is the behaviour Inspectarr has always had, and it does not change until you raise remediate_at.
Configure both under Settings → Rules → Remediation & Severity. The page shows the resulting bands as you change them.
With the default extension list [.exe, .zip, .bat, .msi, .js, .vbs, .dmg, .rar]:
remediate_at |
.exe .bat .msi .js .vbs .dmg
|
.zip .rar
|
|---|---|---|
LOW (default) |
deleted | deleted |
CRITICAL |
deleted | quarantined |
Raising it to CRITICAL means executables are still removed on sight, while archive-only matches wait for you to look.
A quarantined torrent is paused and listed on the Quarantine page awaiting a decision. Nothing is deleted and nothing expires unless you configure a timeout.
Quarantine involves no AI. Severity is entirely deterministic.
| Action | What happens |
|---|---|
| Release | The torrent is resumed and the hold cleared. Use when it was a false positive. |
| Keep paused | The hold is closed but the torrent stays paused. Use when you want it stopped without deleting it. |
| Delete | Blocklisted in the *arr and removed from the torrent client — the same remediation that would have happened automatically. Asks for confirmation. |
An action only resolves the hold once the underlying operation succeeds. If the torrent client refuses to resume, the entry stays held and visible rather than silently vanishing from the queue while still paused.
Inspectarr pauses first, but does not abandon the hold if the client refuses — the torrent still needs a decision. The entry is flagged not paused on the Quarantine page, because a torrent that is still downloading should not be presented as contained.
By default a hold waits indefinitely. Set a timeout only if you want holds to resolve themselves.
remediation:
quarantine_timeout_minutes: 0 # 0 = hold indefinitely (default)
quarantine_timeout_action: release # "release" or "remediate"The default action is release because an expiring timer means nobody looked — which is not the same as deciding the release was malicious. Choosing remediate is an explicit decision to let a timer delete.
If a timed-out deletion fails, the entry stays held rather than being marked deleted.
Every flagged release writes an inspection record regardless of the band, including catches below min_severity that are never acted on. Each record stores the aggregate risk level, the decision, and one row per finding with its own severity — so months later you can still see exactly what was seen and why it was handled that way.
Events written to the log: torrent_quarantined, quarantine_released, quarantine_kept, quarantine_remediated, quarantine_timeout_released, quarantine_timeout_remediated, below_severity_floor.
- Rules — the conditions that produce findings
- Detection & Actions — the full scan and action sequence
-
Configuration — every
remediationkey