ecluse:ecluse-core
Safe HaskellNone
LanguageGHC2021

Ecluse.Core.Rules.Types

Description

The closed rule vocabulary, the evidence a rule reads, rule verdicts, and policy decisions. Ecluse.Core.Rules binds these values to capabilities and evaluates them. Configuration selects built-in rules and cannot supply evaluation closures.

Synopsis

The built-in rule vocabulary

data Rule Source #

The closed rule vocabulary configuration selects. prepare binds its capabilities.

Constructors

AllowScope Scope

Unconditionally allow every package under the given scope.

AllowIfOlderThan NominalDiffTime

Delay new versions, so a malicious publish is found and removed before a build installs it.

DenyInstallTimeExecution

Deny npm versions that declare install scripts. Other adapters refuse this rule at boot.

DenyExternalDependencies

Deny a version whose installable dependency a client would fetch from outside the registry, such as an npm git or URL spec.

DenyIfYanked

Refuse versions carrying the registry yank flag.

DenyIfDeprecated

Refuse versions carrying the registry deprecation flag, including obsolete release lines.

DenyByIdentity Text

A hard deny for one package or package@version, at top precedence, so it also revokes mirrored copies.

AllowByIdentity Text

Allow one package or package@version, including a fix the exact fix match cannot recognise.

AllowIfRemediatesCve AllowIfRemediatesCveParams

Admit an advisory's exact fix ahead of the quarantine, on the terms AllowIfRemediatesCveParams sets.

DenyIfCve DenyIfCveParams

Deny versions an advisory at or above the CVSS threshold affects, including historical mirror dependencies.

DenyIfKnownMalicious FailureAlignment

Deny versions affected by an active primary MAL advisory, independently of scores.

DenyIfEpss DenyIfEpssParams

Deny on a known EPSS score at or above the threshold. An individual missing score abstains.

Instances

Instances details
Show Rule Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Methods

showsPrec :: Int -> Rule -> ShowS #

show :: Rule -> String #

showList :: [Rule] -> ShowS #

Eq Rule Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Methods

(==) :: Rule -> Rule -> Bool #

(/=) :: Rule -> Rule -> Bool #

data RuleType Source #

Parameter-free rule identity for configuration and ecosystem blocks.

Instances

Instances details
WireVocab RuleType Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Generic RuleType Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Associated Types

type Rep RuleType 
Instance details

Defined in Ecluse.Core.Rules.Types

type Rep RuleType = D1 ('MetaData "RuleType" "Ecluse.Core.Rules.Types" "ecluse-0.4.0-inplace-ecluse-core" 'False) (((C1 ('MetaCons "AllowScopeType" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "AllowIfOlderThanType" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "AllowByIdentityType" 'PrefixI 'False) (U1 :: Type -> Type))) :+: (C1 ('MetaCons "AllowIfRemediatesCveType" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "DenyIfCveType" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "DenyIfKnownMaliciousType" 'PrefixI 'False) (U1 :: Type -> Type)))) :+: ((C1 ('MetaCons "DenyIfEpssType" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "DenyIfYankedType" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "DenyIfDeprecatedType" 'PrefixI 'False) (U1 :: Type -> Type))) :+: (C1 ('MetaCons "DenyInstallTimeExecutionType" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "DenyExternalDependenciesType" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "DenyByIdentityType" 'PrefixI 'False) (U1 :: Type -> Type)))))

Methods

from :: RuleType -> Rep RuleType x #

to :: Rep RuleType x -> RuleType #

Show RuleType Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Eq RuleType Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Ord RuleType Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Universe RuleType Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Methods

universe :: [RuleType] #

type Rep RuleType Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

type Rep RuleType = D1 ('MetaData "RuleType" "Ecluse.Core.Rules.Types" "ecluse-0.4.0-inplace-ecluse-core" 'False) (((C1 ('MetaCons "AllowScopeType" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "AllowIfOlderThanType" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "AllowByIdentityType" 'PrefixI 'False) (U1 :: Type -> Type))) :+: (C1 ('MetaCons "AllowIfRemediatesCveType" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "DenyIfCveType" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "DenyIfKnownMaliciousType" 'PrefixI 'False) (U1 :: Type -> Type)))) :+: ((C1 ('MetaCons "DenyIfEpssType" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "DenyIfYankedType" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "DenyIfDeprecatedType" 'PrefixI 'False) (U1 :: Type -> Type))) :+: (C1 ('MetaCons "DenyInstallTimeExecutionType" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "DenyExternalDependenciesType" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "DenyByIdentityType" 'PrefixI 'False) (U1 :: Type -> Type)))))

ruleType :: Rule -> RuleType Source #

Discard a rule's parameters while retaining its canonical type.

data DenyIfCveParams Source #

DenyIfCve's configured behaviour, a record so its selectors stay total under the sum.

Constructors

DenyIfCveParams 

Fields

data DenyIfEpssParams Source #

DenyIfEpss's configured behaviour, the EPSS twin of DenyIfCveParams.

Constructors

DenyIfEpssParams 

Fields

data AllowIfRemediatesCveParams Source #

AllowIfRemediatesCve's configured behaviour. Configuration states both choices, and nothing defaults them.

Constructors

AllowIfRemediatesCveParams 

Fields

data RemainingAdvisories Source #

What the fast lane does with a partial fix: an exact fix that another advisory still affects.

Constructors

AbstainOnRemaining

Abstain, so the partial fix waits out the quarantine.

Differential DifferentialLimits

Admit when the remaining advisories' stored scores sit inside the limits.

data DifferentialLimits Source #

The differential's limits. They compare stored scores, which proves no reduced exposure.

Constructors

DifferentialLimits 

Fields

data ScoreGap Source #

A minimum difference between the highest fixed and the highest remaining score.

Constructors

NoGapRequired

No gap condition, so no fixed score is needed.

GapOfAtLeast Double

The highest known fixed score must exceed the highest remaining one by at least this.

Instances

Instances details
Show ScoreGap Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Eq ScoreGap Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

defaultDifferentialLimits :: DifferentialLimits Source #

The shipped limits, which fill omitted keys in differential mode only. They are product defaults, not safety boundaries.

ruleName :: Rule -> Text Source #

Canonical rule name used for boot-order ties, logs, and denial messages.

readsAdvisories :: Rule -> Bool Source #

Whether a rule reads the advisory database, so a rule set holding one waits a bounded while for the first sync.

deniesOnAdvisories :: Rule -> Bool Source #

Whether a rule refuses when the advisory database cannot answer, which makes an advisory store mandatory.

requiresEpss :: Rule -> Bool Source #

Whether a rule reads EPSS scores, which makes Pilot's enrichment and a consumer's check of it mandatory.

ruleDenies :: Rule -> Bool Source #

Whether a rule can only refuse or abstain, so removing it cannot refuse a version the whole policy admits.

Precedence and reach

data PrecededRule Source #

A rule with explicit precedence. bootOrder orders rules, never a derived Ord.

Constructors

PrecededRule 

Fields

Instances

Instances details
Show PrecededRule Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Eq PrecededRule Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

data RuleReach Source #

The phases a rule applies at. Every rule applies at admission, so a deny limited to it never removes a stored version.

Constructors

AdmissionAndRevocation

The gate, the mirror worker's ingest, and the Dredger's revocation all read the rule.

AdmissionOnly

The gate and the mirror worker's ingest read the rule. The Dredger does not.

Instances

Instances details
Show RuleReach Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Eq RuleReach Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

revocationRules :: [PrecededRule] -> [PrecededRule] Source #

The rules the Dredger evaluates. Only a deny may be AdmissionOnly, so this never blocks what the policy admits.

defaultPrecedence :: Rule -> Int Source #

The rule type's precedence when configuration omits one. bootOrder breaks ties.

defaultAllowIfOlderThanPrecedence :: Int Source #

Default precedence of AllowIfOlderThan: the lowest band, a quarantine that yields to allow-lists and every deny.

defaultAllowIfRemediatesCvePrecedence :: Int Source #

Admit security fixes ahead of the quarantine, yielding to AllowScope and to every deny.

defaultAllowScopePrecedence :: Int Source #

Default precedence of AllowScope: above the quarantine, because an allow-list is a stronger statement.

defaultDenyIfCvePrecedence :: Int Source #

Outrank the quarantine, remediation, and scope allows, and yield to an AllowByIdentity override.

defaultDenyIfEpssPrecedence :: Int Source #

Default precedence of DenyIfEpss: the rung of DenyIfCve, which reads the same database. A tie resolves by name.

defaultAllowByIdentityPrecedence :: Int Source #

An identity pin overrides scored advisory denies, and yields to MAL, availability, install-code, dependency, and identity denies.

defaultDenyInstallTimeExecutionPrecedence :: Int Source #

Default precedence of DenyInstallTimeExecution: the deny band, above every allow default.

What a rule reads about one version

data Fact a Source #

One fact of the evidence. A determined absence (Known Nothing) stays distinct from Unread, no reading at all.

Constructors

Known a

The fact was read, and is whatever it says.

Unread

Nothing read this fact, so a rule that needs it cannot decide.

Instances

Instances details
Show a => Show (Fact a) Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Methods

showsPrec :: Int -> Fact a -> ShowS #

show :: Fact a -> String #

showList :: [Fact a] -> ShowS #

Eq a => Eq (Fact a) Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Methods

(==) :: Fact a -> Fact a -> Bool #

(/=) :: Fact a -> Fact a -> Bool #

data RuleEvidence Source #

What the engine reads about one version. Identity is unconditional, because a store listing establishes it.

Constructors

RuleEvidence 

Fields

Instances

Instances details
Show RuleEvidence Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Eq RuleEvidence Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

completeEvidence :: PackageDetails -> RuleEvidence Source #

Every fact present, the shape the serve, admission, and mirror paths always hold.

identityEvidence :: PackageName -> Version -> RuleEvidence Source #

Identity alone, as an authenticated store listing establishes it. A rule reading any other fact cannot decide.

Evaluation

data EvalContext Source #

Ambient information a rule may need that is not part of the package itself.

Constructors

EvalContext 

Fields

  • ctxNow :: UTCTime

    The wall-clock "now" for age-based rules.

  • ctxAdvisoryEtag :: Maybe DbEtag

    The advisory generation active at the audit line. A shadow swap can make it differ from the one evaluated.

Instances

Instances details
Show EvalContext Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Eq EvalContext Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

mkEvalContext :: IO UTCTime -> IO (Maybe DbEtag) -> IO EvalContext Source #

Build the context from the mount's injected clock. The advisory ETag is audit-only and cannot affect the decision.

data RuleVerdict Source #

A deterministic verdict the harness never retries. Allow, Deny, and fail-closed CannotVet are decisive.

Constructors

Allow Reason

This rule admits the package. Decisive.

Deny (Maybe DbEtag) Reason

A decisive denial, with its acquired advisory ETag or none for a non-advisory rule.

NoDecision Reason

This rule has no opinion. The reason stays for the audit trail. A no-op.

CannotVet FailureAlignment Inability

Deterministic inability to vet, never retried. FailDeny yields Undecidable, and FailNoDecision abstains.

Instances

Instances details
Show RuleVerdict Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Eq RuleVerdict Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

data RuleEvaluation Source #

One rule's evaluation. Only the harness creates Unavailable, from faults. Decisive outcomes decide the version, and the rest join the audit trail.

Constructors

Decided RuleVerdict

The rule returned a verdict, and the harness takes it at face value.

Unavailable Transience FailureAlignment Inability

A fault, timeout, or open breaker, with retry advice. FailDeny yields Undecidable, and FailNoDecision abstains.

data FailureAlignment Source #

Refusal or abstention when a rule cannot vet or its evaluation faults. No alignment admits unvetted bytes.

Constructors

FailDeny

Fail closed. An uncomputable result is decisive: the version is not admitted.

FailNoDecision

Fail open. An uncomputable result is a no-op: the rule simply does not fire.

data Decision Source #

The decision for a version against a whole rule set. It credits the deciding rule by name (ruleName).

Constructors

Admitted Text Reason [SkippedCheck]

Admitted by the named rule, with the configured checks the admission did not benefit from.

Blocked Text (Maybe DbEtag) Reason

Blocked by the named rule, with the advisory ETag that supplied its evidence and its reason.

BlockedByDefault [Reason]

No rule was decisive, so the version is denied. It carries every non-decisive reason, in boot order.

Undecidable Transience Reason

A fail-closed rule won without vetting. Packuments omit the version, and artifact requests fail by Transience.

Instances

Instances details
Show Decision Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Eq Decision Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

data SkippedCheck Source #

A configured check the winning allow did not benefit from. A check the engine never ran never reads as passed.

Constructors

SkippedUnavailable Text Inability

The check ran, could not vet the version, and its fail-open alignment let the fold move on.

Unreached Text

An earlier allow in the boot order decided, so the engine never ran the check.

Instances

Instances details
Show SkippedCheck Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Eq SkippedCheck Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

skippedChecks :: Decision -> [SkippedCheck] Source #

The skipped-check evidence a decision carries: an admission's, and none for any other outcome.

Why a rule reached its result

data Reason Source #

Why a rule reached its result, as facts. renderReason writes the sentence.

Constructors

ScopeAllowListed Scope

AllowScope admits: the package is under the scope it allows.

ScopeNotAllowListed Scope

AllowScope abstains: the package is not under the scope it allows.

PublishedLongEnough NominalDiffTime NominalDiffTime

AllowIfOlderThan admits: the version's age, then the minimum it met.

PublishedTooRecently NominalDiffTime NominalDiffTime

AllowIfOlderThan abstains: the version's age, then the minimum it has not met.

PublishTimeUnknown

AllowIfOlderThan abstains: the metadata was read and carries no publish time.

RunsOnInstall Text

DenyInstallTimeExecution denies: how installing the version runs code.

NothingRunsOnInstall

DenyInstallTimeExecution abstains: installing the version runs no code.

InstallCodeUndetermined

DenyInstallTimeExecution abstains: whether installing runs code is not yet determined.

FetchesOutside Text

DenyExternalDependencies denies: the dependency a client would fetch from outside the registry.

DependenciesThroughRegistry

DenyExternalDependencies abstains: every installable dependency resolves through the registry.

DependencySourcesUndetermined

DenyExternalDependencies abstains: where the dependencies install from is not determined.

VersionYanked

The version carries the yank flag.

VersionNotYanked

The version carries no yank flag.

VersionDeprecated

The version carries the deprecation flag.

VersionNotDeprecated

The version carries no deprecation flag.

IdentityRevoked Text

DenyByIdentity denies: the identity the operator revoked.

IdentityNotRevoked Text

DenyByIdentity abstains: the version is not the identity it revokes.

IdentityAllowListed Text

AllowByIdentity admits: the identity the operator allow-listed.

IdentityNotAllowListed Text

AllowByIdentity abstains: the version is not the identity it allows.

Remediates AdvisoryIds

AllowIfRemediatesCve admits: the advisories this version is the exact fix for, with none still affecting it.

RemediatesWithinLimits ScoreComparison

AllowIfRemediatesCve admits a partial fix whose remaining advisories sit inside the limits.

FixesButStillAffected AdvisoryIds AdvisoryIds

AllowIfRemediatesCve abstains on a partial fix: the advisories it genuinely fixes, then those still affecting it.

RemediationBeyondLimits ScoreComparison LimitShortfalls

AllowIfRemediatesCve abstains on a partial fix outside the limits, with every condition it failed.

FixStillApplies AdvisoryIds

AllowIfRemediatesCve abstains: every advisory naming this version as its fix still affects it through another range.

FixesNoAdvisory

AllowIfRemediatesCve abstains: no advisory names this version as its fix.

AffectedBy AdvisoryScore Double AdvisoryIds

An advisory deny fires: the score it gates on, its threshold, and the affecting advisories.

KnownMalicious AdvisoryIds

Active primary MAL advisories affect the version, independently of scores.

NoKnownMaliciousAdvisory

No active primary MAL advisory affects the version.

NotAffectedAtThreshold AdvisoryScore

An advisory deny abstains: no advisory at or above its threshold affects the version.

RuleUnable Text Inability

The named rule could not vet the version. The engine's fold builds this, never a rule.

Instances

Instances details
Show Reason Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Eq Reason Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Methods

(==) :: Reason -> Reason -> Bool #

(/=) :: Reason -> Reason -> Bool #

reasonAdvisories :: Reason -> [Text] Source #

The advisories still affecting the version, never one it fixes. Every constructor is matched, so a new reason cannot drop out.

data AdvisoryIds Source #

The advisories a reason names, at least one. mkAdvisoryIds evaluates every identifier, so no matching is deferred.

Instances

Instances details
Show AdvisoryIds Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Eq AdvisoryIds Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

mkAdvisoryIds :: NonEmpty Text -> AdvisoryIds Source #

Name the advisories. Evaluating the result evaluates every identifier.

unAdvisoryIds :: AdvisoryIds -> NonEmpty Text Source #

The identifiers, in the order the rule found them.

data Inability Source #

Why a rule could not vet a version. Every holder names the rule in a field of its own.

Constructors

PublishTimeUnread

Nothing read the publish time the rule decides on.

InstallSignalUnread

Nothing read the install-time execution signal the rule decides on.

AvailabilityUnread

Nothing read the availability flag.

DependencySourcesUnread

Nothing read where the installable dependencies come from.

NoDatabaseLoaded

No advisory database is loaded.

PushPastMaximum AdvisoryAge

The serving advisory push is older than its maximum.

PushUndated

The store gave no publication time for the serving advisory push.

SourceBreakerOpen

The rule's circuit breaker is open, so the read was not attempted.

EvaluationFailed

The read was given up. A client reads this in place of the fault's detail.

RuleThrew Text

The rule or its read threw: the exception as text.

AttemptTimedOut

One attempt of the read ran past its timeout.

Instances

Instances details
Show Inability Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Eq Inability Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

data AdvisoryScore Source #

The score an advisory rule compares.

Constructors

Cvss 
Epss 

Instances

Instances details
Show AdvisoryScore Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Eq AdvisoryScore Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

data ScoreComparison Source #

What the differential compared for one partial fix: the advisories on each side, their highest scores, and the limits.

Constructors

ScoreComparison 

Fields

data ScoreSides Source #

The highest stored score among the genuinely fixed advisories, and among the remaining ones.

Instances

Instances details
Show ScoreSides Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Eq ScoreSides Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

data ScoreReading Source #

A score the advisory artifact stores. Unscored never reads as zero.

Constructors

Scored Double 
Unscored 

Instances

Instances details
Show ScoreReading Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Eq ScoreReading Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

data LimitShortfall Source #

One differential condition a partial fix failed.

Constructors

RemainingAboveCeiling AdvisoryScore

The highest remaining score is past its ceiling: above it for CVSS, at or above it for EPSS.

RemainingUnscored AdvisoryScore AdvisoryIds

These remaining advisories store no score of this kind.

FixedUnscored AdvisoryScore

No genuinely fixed advisory stores a score of this kind, so an enabled gap cannot hold.

GapBelowMinimum AdvisoryScore

The highest fixed score exceeds the highest remaining one by less than the minimum gap.

data LimitShortfalls Source #

The conditions a partial fix failed, at least one. mkLimitShortfalls evaluates every one.

mkLimitShortfalls :: NonEmpty LimitShortfall -> LimitShortfalls Source #

Name the failed conditions. Evaluating the result evaluates every one.

unLimitShortfalls :: LimitShortfalls -> NonEmpty LimitShortfall Source #

The failed conditions, in the order the rule checked them.

data AdvisoryAge Source #

One reading of a push's age against its maximum. An audit line and an alarm render the same reading.

Instances

Instances details
Show AdvisoryAge Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Eq AdvisoryAge Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Unavailability

data Transience Source #

Whether a retry can help: a transient fault serves 503, and an internal or parse fault 500.

Constructors

WillResolve (Maybe RetryAfter)

A retry may succeed after an outage, timeout, or open breaker. RetryAfter suggests a client delay.

WontResolve

Not expected to self-heal, so the request is a 500, never a 503.

Instances

Instances details
Show Transience Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Eq Transience Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

newtype RetryAfter Source #

A Retry-After delay in whole seconds, never confused with another integer on its way to a header or a sweep's wait.

Constructors

RetryAfter Int