Crate dregs

Expand description

Dregs: fraud and abuse scoring for the users of your application.

Send events from your backend, read back the scores and the observations behind them:

use dregs::{Client, Event};
use serde_json::json;

let client = Client::from_env()?;

client
    .track(
        Event::new("user.signup", "user_12345")
            .data(json!({ "plan": "pro" }))
            .identity_data(json!({ "email": "ada@example.com" })),
    )
    .await?;

let scores = client.identities().scores("user_12345").await?;

if scores.authenticity().is_some_and(|authenticity| authenticity < 40) {
    hold_for_review("user_12345").await;
}

Scoring is asynchronous, so scores appear moments after the events that move them rather than in the same breath. See https://dregs.com/manual/api/ for the API this wraps.

The client is async and runs on Tokio, through reqwest.

§Groups on track

Pass the organizations, teams, or workspaces the user is acting in, and Dregs makes the identity a member of each. An event carries at most one group of each type:

use dregs::{Event, Group};
use serde_json::json;

client
    .track(
        Event::new("user.login", "user_12345")
            .group(Group::organization("org_678").data(json!({ "name": "Acme Inc" })))
            .group(Group::new("team", "team_42")),
    )
    .await?;

§History, links, and past cycles

let history = client.identities().history("user_12345", Some(10)).await?;

if let Some(cycle_id) = history.last().and_then(|entry| entry.cycle_id) {
    let older = client.identities().analysis_cycle("user_12345", cycle_id).await?;
}

for link in client.identities().links("user_12345").await? {
    println!("{:?} {:?}", link.identity_id, link.link_type);
}

§Disregarding an identity

Leave your own staff and test accounts out of scoring and escalations:

use dregs::IdentityUpdate;

client
    .identities()
    .update("qa_bot_7", IdentityUpdate::new().disregarded(true))
    .await?;

§Asking for a review

Dregs’s AI reviewer looks over an identity’s analysis in the background; read the result back later with Identities::reviews.

let review = client
    .identities()
    .review("user_12345", Some("This is a long-standing customer."))
    .await?;

§Listing and paging

Every namespace with a list() returns one Page at a time, numbered from 0, and a list_all() that walks every page as a stream. Filters you leave out are not sent.

use dregs::{ListIdentities, Order};
use futures_util::TryStreamExt;

let page = client
    .identities()
    .list(ListIdentities::new().term("example.com").page_size(50))
    .await?;

println!("{} match", page.total_elements);

let mut identities = client.identities().list_all(
    ListIdentities::new().group("org_678").sort("humanityScore").order(Order::Asc),
);

while let Some(identity) = identities.try_next().await? {
    println!("{:?}", identity.id);
}

§Groups

Client::groups reads groups back, and keeps Dregs in step when something changes outside an event:

use dregs::Group;
use serde_json::json;

client
    .groups()
    .create(Group::organization("org_678").data(json!({ "name": "Acme Inc" })))
    .await?;

client.groups().add_member("team", "team_42", "user_12345").await?;
client.groups().remove_member("team", "team_42", "user_12345").await?;

§Events, devices, and escalations

use dregs::{EscalationStatus, ListEscalations, ListEvents};
use futures_util::TryStreamExt;

let events = client.events().list(ListEvents::new().identity("user_12345")).await?;

client.devices().update("a1b2c3d4e5", true).await?;

let mut open = client
    .escalations()
    .list_all(ListEscalations::new().status(EscalationStatus::Open));

while let Some(escalation) = open.try_next().await? {
    if let Some(id) = escalation.id {
        client.escalations().update(id, EscalationStatus::Acknowledged).await?;
    }
}

let summary = client.escalations().summary().await?;

§Features

rustls (default): TLS through rustls, verifying certificates with the platform’s verifier.
native-tls: TLS through the operating system’s library instead. Turn off default features to drop rustls.

Modules§

webhooks: Verifying webhooks Dregs sends you.

Structs§

Analysis: One analysis cycle: the scores an identity was given, and why.
ApiError: Dregs answered, and the answer was an error.
Badge: A label Dregs applied to an identity, from an analyzer or a badge rule.
Client: A Dregs client.
ClientBuilder: Builds a Client with settings other than the defaults.
Device: A browser or device Dregs has seen, identified by its fingerprint.
Devices: Read the devices Dregs has seen, and disregard them. Get one from Client::devices.
Escalation: An escalation an escalation rule opened against an identity.
EscalationSummary: How many escalations are in each status.
Escalations: Read the escalations your escalation rules open, and move them along. Get one from Client::escalations.
Event: A backend event to record against an identity, passed to Client::track.
Events: Read the events Dregs has recorded. Get one from Client::events. To record one, use Client::track.
Group: A group the user is acting in, such as their organization, team, or workspace.
GroupReference: A pointer to a group, as it appears on a TrackedEvent.
Groups: Read and manage groups: the organizations, teams, or workspaces your users belong to. Get one from Client::groups.
Identities: Read identities, their scores, and their analysis. Get one from Client::identities.
Identity: A user Dregs is tracking, and their current scores.
IdentityReview: A review of an identity’s analysis, written by Dregs’s AI reviewer.
IdentityUpdate: The changes Identities::update makes. Set at least one.
LinkedIdentity: Another identity Dregs believes is connected to this one, such as by a shared device.
ListDevices: The filters and paging for Devices::list and Devices::list_all.
ListEscalations: The filters and paging for Escalations::list and Escalations::list_all.
ListEvents: The filters and paging for Events::list and Events::list_all.
ListGroups: The filters and paging for Groups::list and Groups::list_all.
ListIdentities: The filters and paging for Identities::list and Identities::list_all.
Observation: One analyzer’s finding, and the reasoning behind a slice of a score.
Page: One page of a list call.
Reference: A pointer to another resource: its id, a label for display, and its API path.
Score: One category’s score.
ScoreHistoryEntry: The scores one past analysis cycle produced.
Scores: An identity’s four category scores.
TrackResult: The outcome of a Client::track call.
TrackedEvent: An event Dregs recorded. To record one, use Client::track.
TrackedGroup: An organization, team, workspace, or whatever your application groups users into, as Dregs has recorded it.

Enums§

ApiErrorKind: Which error Dregs answered with, by HTTP status.
Category: The four categories Dregs scores an identity in.
Error: Everything this crate returns as an error.
EscalationSeverity: How serious an escalation is, as its rule set it.
EscalationStatus: Where an escalation stands.
Order: Which way a list is sorted.

Constants§

BASE_URL_ENV: The environment variable the base URL is read from.
DEFAULT_BASE_URL: The API root used when none is configured.
DEFAULT_GROUP_TYPE: The group type used when a Group is given none.
DEFAULT_MAX_RETRIES: How many times a failed request is retried, when no limit is configured.
DEFAULT_TIMEOUT: How long a request may take before it is abandoned, when none is configured.
SECRET_KEY_ENV: The environment variable the secret key is read from.

Type Aliases§

ItemStream: A stream of every item a list_all() call matches, fetching pages as it goes.
Result: A Result whose error is this crate’s Error.

Crate dregs

Crate dregs Copy item path

§Groups on track

§History, links, and past cycles

§Disregarding an identity

§Asking for a review

§Listing and paging

§Groups

§Events, devices, and escalations

§Features

Modules§

Structs§

Enums§

Constants§

Type Aliases§

Crate dregs