SPB Git

Repository Public License

security-engine.md 15.1 KB

# ORIX Secure — Security engine

Sources: Packages/ORIXSecureEngines/Sources/ORIXSecureEngines/ — SecuritySignals.swift (SystemSecurityProbe), SecurityAssessmentEngine.swift, Checklist.swift, InvestigationEngine.swift, DeviceSnapshot.swift (PlatformLimits); wiring in App/Sources/Core/AppModel.swift.

# 1. Pipeline

flowchart TD
    DP["SystemDeviceProbe.snapshot()<br/>@MainActor"] --> DS["DeviceSnapshot"]
    SC["AppModel.screenCaptured()<br/>UITraitCollection.sceneCaptureState"] --> SP
    SP["SystemSecurityProbe.signals(isSimulator:screenCaptured:)"] --> SS["SecuritySignals"]
    ST[("LocalStore.responses()<br/>StoredAnswer rows")] --> CR["[ChecklistResponse]"]
    NC["NetworkController.assess()<br/>NetworkAssessment.findings"] --> CF["contributed: [Finding]<br/>AppModel.networkFindings"]

    DS --> ENG["SecurityAssessmentEngine.assess(device:signals:responses:contributed:now:)"]
    SS --> ENG
    CR --> ENG
    CF --> ENG

    ENG --> AUTO["automatic<br/>9 findings + 1 conditional"]
    ENG --> CHK["checklist<br/>one finding per ChecklistCatalog.security item"]
    ENG --> CON["contributed<br/>carried unchanged"]
    ENG --> NA["notAssessable<br/>PlatformLimits.securityAssessments"]

    AUTO --> SA["SecurityAssessment"]
    CHK --> SA
    CON --> SA
    NA --> SA
    SA --> SUM["AssessmentSummary<br/>counts by state, coverage, highest severity"]
    SA --> ACT["actions: attention findings, prioritized()"]
    SA --> PEND["pendingConfirmations"]

AppModel runs the pipeline in init, in refresh() (scene becomes active, explicit refresh) and in recompute() (a checklist answer changes, network findings arrive). The engine is a pure function of its inputs; tests inject FixedDeviceProbe and FixedSecurityProbe.

Contributed findings are those of NetworkAssessment.findings(for:) — connection, addresses, proxy, VPN indicator, Wi-Fi security (see network.md). Results of the user-started probes (DNS, latency, TLS, HTTPS) are not contributed to the security assessment.

# 2. Signals read by SystemSecurityProbe

Signal API Notes
passcodeSet: Reading<Bool> LAContext.canEvaluatePolicy(.deviceOwnerAuthentication); LAError.passcodeNotSet gives measured(false) Any other error gives .unavailable(.failed).
biometryKind, biometryEnrolled, biometryLockedOut LAContext.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics), biometryType biometryNotAvailable gives .unsupportedOnDevice when there is no sensor, else .permissionRequired.
secureEnclaveAvailable CryptoKit.SecureEnclave.isAvailable
appAttestSupported DCAppAttestService.shared.isSupported .unavailable(.simulator) in the Simulator. No attestation is performed.
debuggerAttached sysctl(CTL_KERN, KERN_PROC, KERN_PROC_PID), flag P_TRACED This process only.
integrityIndicators, integrityChecksPerformed FileManager.fileExists, Data.write, _dyld_image_count / _dyld_get_image_name, ProcessInfo.environment Section 5. Skipped in the Simulator (performed == 0).
fileProtection: Reading<String> Writes a probe file with .completeFileProtection, reads FileAttributeKey.protectionKey, deletes it .unavailable(.simulator) in the Simulator.
screenCaptured Supplied by the app: UIWindowScene.traitCollection.sceneCaptureState == .active .unavailable(.notRequested) when no window scene exists.

# 3. Automatic findings

Each reading that is .unavailable produces the same finding id with state notAvailable, confidence none, verification notVerifiable and the unavailability detail as explanation.

Finding id Input Possible states Severity when attention
device.os.outdated DeviceSnapshot.systemMajorVersion vs. the major version of builtAgainstSDKVersion (Info.plist DTPlatformVersion) Emitted only when the installed major is lower than the SDK major: attention. Otherwise no finding. low; moderate when two or more majors behind
auth.passcode passcodeSet verified / attention / notAvailable high
auth.biometry biometryLockedOut, biometryEnrolled verified / attention (locked out, or not enrolled) / notAvailable low
device.secureEnclave secureEnclaveAvailable verified / notAvailable —
app.integrity integrityIndicators, integrityChecksPerformed verified (heuristic) / attention (heuristic) / notAvailable (0 checks) high
app.debugger debuggerAttached verified / attention / notAvailable low
app.dataProtection fileProtection compared with FileProtectionType.complete.rawValue verified / attention / notAvailable low
app.attest appAttestSupported verified / notAvailable (unsupported or unreadable) —
device.screenCapture screenCaptured verified / attention / notAvailable low
device.restart DeviceSnapshot.lastBoot (sysctl kern.boottime) verified / attention when days since boot ≥ SecurityAssessmentEngine.restartSuggestionDays (30) / notAvailable low

Notes:

  • device.os.outdated uses the SDK the build was compiled against as a dated reference; the engine works offline and its notInspected text says it does not know the latest release.
  • app.integrity is the only automatic finding with confidence: .heuristic in both its verified and attention forms; all others are measured / publicAPI.
  • Categories: device (os, Secure Enclave, App Attest, restart), authentication (passcode, biometry), appIntegrity (integrity, debugger, data protection), privacy (screen capture).

# 4. Checklist

ChecklistCatalog.security holds 19 items (sec.*), ChecklistCatalog.privacyItems 16 items (priv.*, consumed by PrivacyAuditEngine). Each ChecklistItem carries a question, the Settings path, expected (default .yes; no catalog item overrides it), importance, isOptional (default false) and validityDays (default 90).

SecurityChecklistEngine.finding(for:response:now:extraEvidence:) — rules in evaluation order:

Condition State Confidence / verification Severity
No response, item not optional userConfirmationRequired none / notVerifiable none
No response, item optional notAssessed none / notVerifiable none
Response older than validityDays (isStale: now − answeredAt > validityDays × 86 400 s) userConfirmationRequired (whatever the answer was) none / notVerifiable none
Answer notApplicable notAvailable userReported / userConfirmed none
Answer notSure userConfirmationRequired none / notVerifiable none
Answer equals expected userConfirmed userReported / userConfirmed none
Answer differs, item optional userConfirmed (explanation says the protection is optional and off; recommendation = item action) userReported / userConfirmed none
Answer differs, item not optional attention userReported / userConfirmed item.importance

Further rules:

  • When several responses exist for one item, the latest answeredAt wins (Dictionary(uniquingKeysWith:)). LocalStore keeps at most one row per item anyway.
  • A checklist finding never has state verified. Its evidence is the answer, the answer date and the Settings path; notInspected states that the app cannot read the setting.
  • sec.updates.current receives one extra measured evidence line, the installed system version.
  • Optional items: sec.lockdown, sec.adp, sec.erase, priv.significant (all with importance: .none).
  • Non-default validity: 30 days sec.updates.current; 60 days sec.passwords.review; 180 days sec.lockdown, sec.adp, priv.safetycheck, priv.significant; 365 days sec.passcode.strength, sec.account.recovery, sec.erase.
  • Items with importance: .high: sec.updates.current, sec.account.2fa, sec.account.devices, sec.profiles.unknown, sec.profiles.mdm, sec.certs.trust.

# 5. Integrity-indicator heuristic

SystemSecurityProbe.integrityIndicators() runs on a physical device only and counts each check in integrityChecksPerformed:

Check Count Indicator id Source recorded
Existence of each path in jailbreakPaths (package-manager apps, Substrate/substitute/libhooker libraries, sshd, /bin/bash, apt/cydia folders, /var/jb, bootstrap markers) 22 path:<path> FileManager.fileExists
Write of a probe file under /private/ (removed if it succeeds) 1 sandbox.write Data.write
Name of every loaded image against injectedLibraryMarkers (mobilesubstrate, substrate, substitute, libhooker, frida, cycript, sslkillswitch, ellekit, systemhook) 1 dyld:<marker> _dyld_get_image_name
DYLD_INSERT_LIBRARIES non-empty 1 dyld.insert ProcessInfo.environment

That is 25 checks. Zero indicators gives app.integrity = verified with the title "No known sign of system modification observed"; one or more gives attention / high with every observation listed as evidence.

Stated limits (they are in the finding's notInspected and explanation):

  • The checks run inside the app sandbox and look for known signs only; tools built to hide from apps avoid them.
  • System files, the kernel and other apps cannot be inspected.
  • "None observed" is an absence of known signs, not proof that the system is unmodified.
  • Each indicator can have a harmless cause; a user who jailbroke the device on purpose will see them.
  • In the Simulator the finding is notAvailable: the checks are not meaningful on a Mac's file system.

# 6. No score

AssessmentSummary(findings:) contains counts only: verified, attention, userConfirmed, awaitingConfirmation, notAvailable, notAssessed, and highestSeverity.

  • assessable = verified + attention + userConfirmed + awaitingConfirmation (excludes notAvailable and optional items never answered).
  • coverage = (verified + attention + userConfirmed) / assessable, or nil when assessable == 0.

Coverage measures how much was looked at. An attention finding raises coverage exactly as a verified one does, so coverage cannot be read as a security level. AssessmentSummary.methodology (seven sentences, shown in the UI and written into the "Summary" section of the security report by ReportBuilder.security) states that no score is computed because a single number would hide what was and was not checked, and that full coverage does not mean absence of risk.

SecurityAssessment.notAssessable always carries PlatformLimits.securityAssessments (8 entries: malware.scan, apps.installed, apps.permissions, safari.history, profiles.list, traffic.others, wifi.router, settings.system); the report lists them under unavailable.

# 7. Investigation engine

InvestigationEngine supports eight Symptom cases: batteryDrain, dataUsage, suspiciousLink, unknownProfile, accountActivity, storageAnomaly, crashes, networkBehavior.

  • plan(for:) returns an InvestigationPlan: five yes/no questions (InvestigationQuestion, answered with ChecklistAnswer), two or three SettingsCheck entries, and the InvestigationTools relevant to the symptom.
  • evaluate(_ input: InvestigationInput) returns an InvestigationResult that keeps four things apart: observations (measured Evidence: system version; thermal state, Low Power Mode, battery, last restart and storage for batteryDrain/crashes; capacity and free space for storageAnomaly; the integrity indicator count when checks ran; the title of each attention tool finding), reported (the user's answers, source "user"), hypotheses, and actions + escalation. notInspected always includes "Whether the device is compromised: no App Store app can determine that."

# Hypothesis support

Hypothesis.Support is lessLikely (0) < possible (1) < supported (2).

  • An ordinary hypothesis is built by the local helper h(id, title, explanation, when:): it is supported when at least one of its conditions holds (the matching phrases become its basis), otherwise possible.
  • Hypotheses are sorted by support descending, then by id. Ordinary ids start with a.–e.; the compromise hypothesis is z.compromise, so with equal support it is listed last.

# The compromise hypothesis

compromiseHypothesis(_:extraBasis:) produces "The device or account has been tampered with". Its support is basis.isEmpty ? .lessLikely : .supported; it is never possible. The basis can only contain:

Basis entry Origin Symptoms
"N known sign(s) of system modification observed" Measured: signals.integrityIndicators non-empty all
"a VPN or profile you do not recognise is installed" Reported: unknownVPN = yes dataUsage
"iOS is not up to date" Reported: upToDate = no suspiciousLink
"nobody you know installed a profile that changes trust or routing" Reported: workDevice = no and installedByApp = no and (hasCertificate or hasVPNProxy = yes) unknownProfile

For batteryDrain, accountActivity, storageAnomaly, crashes and networkBehavior only an observed integrity indicator can move it to supported. The symptom alone never does; the explanation text says it "cannot be confirmed or excluded by an app". Tests withNoEvidenceCompromiseIsAlwaysLastAndLessLikely and compromiseNeedsAConcreteSign cover the rule.

# Tool findings

InvestigationFlowView.evaluate() refreshes the model and passes model.networkFindings + (model.network.tls?.findings ?? []) as toolFindings for networkBehavior, dataUsage and unknownProfile — the connection assessment plus the last certificate check run in this session; other symptoms receive none. In networkBehavior:

  • b.config gains a basis when a tool finding whose id contains proxy is in attention (network.proxy);
  • c.interception gains a basis when a network finding whose id contains tls is in attention (tls.trust, tls.hostname, tls.validity…). It is reachable once the user has run a certificate check in the Network Lab during the session; DNS, latency and HTTPS probe results are not passed.

InvestigationResult.report() builds a ReportDocument of kind .investigation whose hypotheses section opens with "None is a confirmed diagnosis."

# 8. Verification status

  • Covered by package tests on macOS (SecurityAssessmentTests, InvestigationTests): state mapping for every answer, expiry, optional items, summary counts, the compromise rule, JSON round-trip.
  • Not exercised on a physical device: fileProtection, appAttest, the 25 integrity checks (all skipped or unavailable in the Simulator), biometric lockout, and the sceneCaptureState reading during a real recording or AirPlay session.
  • The tests were not re-run while writing this document.
Files main
Menu

Theme