A security check around creates: log, block, handle false positives

Runs the sample. Generated for this page; it reads the connection string from the environment and first remakes the sample database from sample-schema.json.

using ArxSamples.MongoDb;
using ArxSamples.MongoDb.Operations.Create.AdvancedCases;

// The connection string comes from the environment, never from the code (see "Configure the connection").
var connectionString = Environment.GetEnvironmentVariable("ARX_SAMPLES_MONGODB")
    ?? throw new InvalidOperationException("Set the ARX_SAMPLES_MONGODB environment variable to your MongoDB connection string.");

var dbContext = new SampleContext(connectionString);

// Every run starts from the sample data: this deletes and makes again what sample-schema.json lists
// (save the file in the project folder, see Get started).
await dbContext.Direct.ResetAsync();

await new Advanced2_GuardAgainstAttacks().RunAsync(dbContext);

The sample, as it is in the repository.

using ARX.SDK.Services;
using static ArxSamples.MongoDb.SampleOutput;

namespace ArxSamples.MongoDb.Operations.Create.AdvancedCases;

/// <summary>
/// A security check around every create (<see cref="SecurityGuard"/>, in the project root), in four scenarios: a normal
/// request passes through; an attack is logged and the user sees a plain message; repeated attacks block the user; and
/// a false positive, a harmless file header flagged as SQL, is triaged and fixed without blocking anyone.
/// </summary>
/// <remarks>
/// <para>ARX1017 is only raised for a name that is already invalid, so a false positive never stops a call that would
/// otherwise have worked: without the check it would fail with ARX1003. What can be wrong is the label: a harmless name
/// (<c>E-mail (work)</c>, <c>Price (EUR)</c>, <c>notes;</c> pasted into a setting) reported as an attack. Handle it with:</para>
/// <list type="bullet">
/// <item><b>The source of the name:</b> <c>NameSource.Code</c> for names from your code or configuration, so an ARX1017
/// there is logged as a bug and blocks nobody; <c>NameSource.UserInput</c> for names built from what a user sent.</item>
/// <item><b>Strikes, not one event:</b> a single ARX1017 never blocks anyone.</item>
/// <item><b>Triage:</b> the log has ARX's evidence (<c>contains '('</c>); if it's harmless, <c>Unblock</c> the user and
/// fix what let the name through.</item>
/// <item><b>The real fix:</b> map user input to names from a fixed list (headers to attributes, request types to
/// tables), so user input never becomes a name, and neither attacks nor false positives can happen.</item>
/// </list>
/// </remarks>
public sealed class Advanced2_GuardAgainstAttacks : ISample
{
    public string Name => "create-advanced-2-guard-against-attacks";

    public string Title => "A security check around creates: log, block, handle false positives";

    public async Task RunAsync(SampleContext dbContext)
    {
        // One guard for the application (register it as a singleton). Three strikes block a user.
        var guard = new SecurityGuard(blockAfter: 3);

        await Scenario1_ANormalRequestPassesThroughAsync(dbContext, guard);

        await Scenario2_AnAttackIsLoggedAsync(dbContext, guard);

        await Scenario3_RepeatedAttacksBlockTheUserAsync(dbContext, guard);

        await Scenario4_AFalsePositiveAsync(dbContext, guard);
    }

    /// <summary>The "create a contact" endpoint: the posted fields become attributes, so the names come from the user.</summary>
    private static Task<GuardResult<ArxRecordId>> CreateContactAsync(SampleContext dbContext, SecurityGuard guard, string user, Dictionary<string, object> posted)
    {
        var contact = new ArxEntity("contact");

        foreach (var field in posted)
        {
            contact[field.Key] = field.Value;
        }

        return guard.RunAsync(user, "create contact", NameSource.UserInput, () => dbContext.Service.CreateAsync(contact));
    }

    /// <summary>1. A normal request goes through the guard untouched.</summary>
    private static async Task Scenario1_ANormalRequestPassesThroughAsync(SampleContext dbContext, SecurityGuard guard)
    {
        Step("1. A normal request passes through");

        var result = await CreateContactAsync(dbContext, guard, "ana", new Dictionary<string, object>
        {
            ["first_name"] = "Ana",
            ["last_name"] = "Guard-C1",
            ["email"] = "[email protected]",
        });

        Show($"ana: {result.Outcome}, contact {result.Value}");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * db.contact.find({ last_name: "Guard-C1" }, { first_name: 1, email: 1 })
         * -- Expect: 1 document: Ana, [email protected].
         * ===========================================================
         */
    }

    /// <summary>2. A field name carrying SQL: ARX refuses it (ARX1017), the guard logs it and the user sees a plain message.</summary>
    private static async Task Scenario2_AnAttackIsLoggedAsync(SampleContext dbContext, SecurityGuard guard)
    {
        Step("2. An attack is logged; the user sees a plain message");

        var result = await CreateContactAsync(dbContext, guard, "mallory", new Dictionary<string, object>
        {
            ["first_name"] = "Mallory",
            ["last_name"] = "Guard-C2",
            ["notes\") VALUES ('x'); DROP TABLE contact; --"] = "x",
        });

        Show($"mallory sees: \"{result.ForTheUser}\"");
        var logged = guard.Events[^1];
        Show($"security log: {logged.Kind}, {logged.User}, {logged.Action}");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * db.contact.countDocuments({ last_name: "Guard-C2" })
         * -- Expect: 0: nothing created.
         * ===========================================================
         */
    }

    /// <summary>3. Two more attempts make three strikes: the user is blocked, and even a valid request isn't attempted.</summary>
    private static async Task Scenario3_RepeatedAttacksBlockTheUserAsync(SampleContext dbContext, SecurityGuard guard)
    {
        Step("3. Repeated attacks block the user");

        foreach (var probe in new[] { "last_name; DROP TABLE account", "email UNION SELECT 1" })
        {
            await CreateContactAsync(dbContext, guard, "mallory", new Dictionary<string, object> { ["first_name"] = "Mallory", [probe] = "x" });
        }

        var valid = await CreateContactAsync(dbContext, guard, "mallory", new Dictionary<string, object>
        {
            ["first_name"] = "Mallory",
            ["last_name"] = "Guard-C3",
        });

        Show($"mallory blocked: {guard.IsBlocked("mallory")}; a valid request: {valid.Outcome}, \"{valid.ForTheUser}\"");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * db.contact.countDocuments({ first_name: "Mallory" })
         * -- Expect: 0: no request from mallory created anything, the last one wasn't even attempted.
         * ===========================================================
         */
    }

    /// <summary>
    /// 4. A false positive: a supplier file's header "E-mail (work)" is used as an attribute name. The parentheses make
    /// ARX flag it as SQL, though it's harmless. One strike doesn't block anyone; triage reads the log, and the fix is
    /// the mapping that should have been there: file headers mapped to known attributes, so user input never becomes a name.
    /// </summary>
    private static async Task Scenario4_AFalsePositiveAsync(SampleContext dbContext, SecurityGuard guard)
    {
        Step("4. A false positive: a harmless file header flagged as SQL");

        var header = new[] { "first_name", "last_name", "E-mail (work)" };
        var row = new object[] { "Sam", "Guard-C4", "[email protected]" };

        var asIs = header.Zip(row).ToDictionary(x => x.First, x => x.Second);
        var refused = await CreateContactAsync(dbContext, guard, "sam", asIs);

        Show($"sam: {refused.Outcome}; blocked: {guard.IsBlocked("sam")} (one strike blocks nobody)");
        Show($"triage reads: {guard.Events[^1].Detail}");

        // The fix: known headers mapped to attributes; anything else is ignored (or reported to the user), never a name.
        var headerMap = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
        {
            ["first_name"] = "first_name",
            ["last_name"] = "last_name",
            ["E-mail (work)"] = "email",
            ["E-mail"] = "email",
        };

        var mapped = header.Zip(row).Where(x => headerMap.ContainsKey(x.First)).ToDictionary(x => headerMap[x.First], x => x.Second);
        var created = await CreateContactAsync(dbContext, guard, "sam", mapped);

        Show($"after the fix: {created.Outcome}, contact {created.Value}");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * db.contact.find({ last_name: "Guard-C4" }, { first_name: 1, email: 1 })
         * -- Expect: 1 document: Sam, [email protected] (created once, after the fix).
         * ===========================================================
         */
    }
}

What every sample is given: the connection string (and the ISample interface the samples implement).

namespace ArxSamples.MongoDb;

/// <summary>One documentation sample: a scenario a real application has, shown end to end.</summary>
public interface ISample
{
    /// <summary>The name to run it alone: <c>dotnet run -- &lt;name&gt;</c>.</summary>
    string Name { get; }

    /// <summary>One line on what it shows.</summary>
    string Title { get; }

    Task RunAsync(SampleContext dbContext);
}

/// <summary>
/// What a sample is given. Every sample gets the connection string; the application's service and catalog
/// (SampleContext.Application.cs) and the plain MongoDB driver read-back helper (SampleContext.Direct.cs) live in their own
/// files, so a sample needs only the files it uses.
/// </summary>
public sealed partial class SampleContext
{
    public SampleContext(string connectionString)
    {
        ConnectionString = connectionString;
    }

    public string ConnectionString { get; }
}

How the samples print: Step for each scenario, Show for what it did, ShowError for an error caught on purpose.

using ARX.SDK;

namespace ArxSamples.MongoDb;

/// <summary>How the samples print: a numbered step for each scenario, then what it did.</summary>
public static class SampleOutput
{
    /// <summary>The start of a scenario: <c>Step("1. By the id Create returned")</c>.</summary>
    public static void Step(string text) => Console.WriteLine($"  > {text}");

    /// <summary>What the scenario did.</summary>
    public static void Show(string text) => Console.WriteLine($"      {text}");

    /// <summary>An ARX error the scenario caught on purpose.</summary>
    public static void ShowError(ArxException exception)
        => Console.WriteLine($"      caught {exception.GetType().Name}: {exception.Message}");
}

The application's ARX service and its schema catalog, created once and shared by the samples.

using ARX.SDK.MongoDb.Services;
using ARX.SDK.Services;

namespace ArxSamples.MongoDb;

/// <summary>The application's ARX service and its schema catalog, shared by the real and advanced samples.</summary>
public sealed partial class SampleContext
{
    private ArxSchemaCatalog? _catalog;
    private ArxMongoDbService? _service;

    /// <summary>The application's schema catalog: collection ids, keys, lookups and selection sets (SampleCatalog.cs).</summary>
    public ArxSchemaCatalog Catalog => _catalog ??= SampleCatalog.Build();

    /// <summary>
    /// One service for the whole application. It shares one MongoDB client per connection string (a client is a
    /// connection pool), so make it once and keep it.
    /// </summary>
    public ArxMongoDbService Service => _service ??= new ArxMongoDbService(ConnectionString, Catalog);
}

The application's schema catalog: every table's id column and keys, and its selection sets.

using ARX.SDK.Services;

namespace ArxSamples.MongoDb;

/// <summary>An account's industry. Stored in account.industry as the enum's number.</summary>
public enum Industry
{
    Retail = 1,
    Manufacturing = 2,
    Healthcare = 3,
    Finance = 4,
    Technology = 5
}

/// <summary>
/// The application's schema catalog: every collection's id and keys, the lookups between collections, and every
/// picklist (selection set), defined once.
/// </summary>
/// <remarks>
/// <para>
/// <b>Ids.</b> On MongoDB the declared id is the document's <c>_id</c>, named in your code by the column you declare
/// (<c>account["account_id"]</c>). A generated string id is an ObjectId ARX makes before the insert and gives back as its
/// 24-character text; a generated Guid is one ARX makes; a supplied id is yours (a country code, a SKU). MongoDB has no
/// sequences, so a generated number isn't offered, and every document has an <c>_id</c>, so there is no NoIdColumn.
/// </para>
/// <para>
/// <b>Keys.</b> Business keys (an account number; a region and a SKU together) let Update, Delete and Retrieve find
/// documents by them. MongoDB enforces them with unique indexes: the sample database has one for each.
/// </para>
/// <para>
/// <b>Lookups.</b> MongoDB has no foreign keys, so the catalog says which field refers to which collection
/// (<c>.Lookup("contact", "account_id", "account")</c>). ARX stores the referenced id as it is stored there (an ObjectId)
/// and reads the field back as an <see cref="ArxEntityReference"/> with the referenced record's display name.
/// </para>
/// <para>
/// <b>Selection sets.</b> A field that only accepts a fixed list of codes: an account's status, a contact's preferred
/// channels (several codes, stored as an array). ARX checks every <see cref="ArxSelectionSetValue"/> against the catalog
/// before anything is sent and stores the codes themselves.
/// </para>
/// </remarks>
public static class SampleCatalog
{
    public static ArxSchemaCatalog Build() => ArxSchemaCatalog.Create()
        .Table("account", ArxIdColumn.Generated<string>("account_id"))
        .Key("account", "account_number")
        .DisplayName("account", "name")
        .Table("contact", ArxIdColumn.Generated<string>("contact_id"))
        .Key("contact", "email")
        .Lookup("contact", "account_id", "account")
        .DisplayName("contact", new[] { "first_name", "last_name" }, " ")
        .Table("country", ArxIdColumn.Supplied<string>("code"))
        .DisplayName("country", "name")
        .Table("product", ArxIdColumn.Supplied<string>("sku"))
        .DisplayName("product", "name")
        .Table("price_list", ArxIdColumn.Generated<string>("price_id"))
        .Key("price_list", "region", "sku")
        .Lookup("price_list", "region", "country")
        .Table("sales_order", ArxIdColumn.Generated<Guid>("order_id"))
        .Key("sales_order", "order_number")
        .Lookup("sales_order", "account_id", "account")
        .Table("activity_log", ArxIdColumn.Generated<string>("log_id"))
        .AddEnum<Industry>("Industry")
        .Add("AccountStatus", ArxSelectionSetKind.String, ("ACTIVE", "Active"), ("ON_HOLD", "On hold"), ("CLOSED", "Closed"))
        .Add("ContactChannels", ArxSelectionSetKind.String, ArxSelectionSetMultiplicity.Array, ("E", "Email"), ("P", "Phone"), ("S", "SMS"))
        .Build();
}

The plain MongoDB.Driver read-back helper, for the samples that show what MongoDB stored.

namespace ArxSamples.MongoDb;

/// <summary>The plain MongoDB driver outside the SDK, for the samples that show what MongoDB stored.</summary>
public sealed partial class SampleContext
{
    private MongoDirectHelper? _direct;

    /// <summary>The plain MongoDB driver outside the SDK, used only to reset the database and to show what was stored.</summary>
    public MongoDirectHelper Direct => _direct ??= new MongoDirectHelper(ConnectionString);
}

Plain MongoDB.Driver, not part of ARX: reads rows back so a sample can show what MongoDB stored.

using MongoDB.Bson;
using MongoDB.Driver;

namespace ArxSamples.MongoDb;

/// <summary>
/// The plain MongoDB driver, outside the SDK: it resets the sample database from Schema/sample-schema.json and shows
/// what was stored. Samples never write through it.
/// </summary>
public sealed class MongoDirectHelper
{
    private readonly IMongoDatabase _database;

    public MongoDirectHelper(string connectionString)
    {
        var url = MongoUrl.Create(connectionString);
        _database = new MongoClient(url).GetDatabase(url.DatabaseName ?? "arx_samples");
    }

    /// <summary>
    /// The sample schema: Schema/sample-schema.json next to the program (the samples' own project), or sample-schema.json
    /// in the project folder (a sample copied from its page, as Get started says).
    /// </summary>
    private static string SchemaPath()
    {
        var candidates = new[]
        {
            Path.Combine(AppContext.BaseDirectory, "Schema", "sample-schema.json"),
            Path.Combine(Directory.GetCurrentDirectory(), "sample-schema.json"),
            Path.Combine(Directory.GetCurrentDirectory(), "Schema", "sample-schema.json")
        };

        return candidates.FirstOrDefault(File.Exists)
            ?? throw new FileNotFoundException("sample-schema.json isn't in the project folder: download it from the Get started page and save it next to Program.cs.");
    }

    /// <summary>Drops the sample database and makes its collections, indexes and validators again.</summary>
    public async Task ResetAsync()
    {
        var schema = BsonDocument.Parse(await File.ReadAllTextAsync(SchemaPath()));

        foreach (var collection in schema["collections"].AsBsonArray.Select(x => x.AsBsonDocument))
        {
            var name = collection["name"].AsString;

            // Only the collections the schema lists are dropped and made again: anything else in the database is left alone.
            await _database.DropCollectionAsync(name);
            var options = new CreateCollectionOptions<BsonDocument>();

            if (collection.TryGetValue("validator", out var validator))
            {
                options.Validator = validator.AsBsonDocument;
            }

            await _database.CreateCollectionAsync(name, options);

            foreach (var index in collection.GetValue("indexes", new BsonArray()).AsBsonArray.Select(x => x.AsBsonDocument))
            {
                var keys = index["keys"].AsBsonDocument;
                var indexOptions = new CreateIndexOptions<BsonDocument> { Unique = index.GetValue("unique", false).AsBoolean };

                if (index.GetValue("partial", false).AsBoolean)
                {
                    indexOptions.PartialFilterExpression = new BsonDocument(keys.Names.Select(x => new BsonElement(x, new BsonDocument("$exists", true))));
                }

                await _database.GetCollection<BsonDocument>(name).Indexes.CreateOneAsync(new CreateIndexModel<BsonDocument>(keys, indexOptions));
            }
        }
    }

    /// <summary>The stored documents a filter finds, as MongoDB's JSON, one line each.</summary>
    public async Task<IReadOnlyList<string>> FindAsync(string collection, string filterJson)
    {
        var documents = await _database.GetCollection<BsonDocument>(collection).Find(BsonDocument.Parse(filterJson)).ToListAsync();
        return documents.Select(x => x.ToJson()).ToList();
    }
}

A security check around ARX calls: suspected injection logged as a security event, strikes, blocking.

using ARX.SDK;

namespace ArxSamples.MongoDb;

/// <summary>Where the names (tables, attributes, match columns) in a call come from. It decides what an ARX1017 means.</summary>
public enum NameSource
{
    /// <summary>A name built from what a user sent (a form field, a file header, a query string): ARX1017 is a suspected attack.</summary>
    UserInput,

    /// <summary>A name from your code or configuration: ARX1017 is a bug in your code, not an attack. Nobody is blocked.</summary>
    Code,
}

/// <summary>What the guard did with a call.</summary>
public enum GuardOutcome
{
    /// <summary>The call ran.</summary>
    Done,

    /// <summary>ARX refused the call with ARX1017; the event is logged and the user got a plain message.</summary>
    Refused,

    /// <summary>The user was already blocked: the call wasn't attempted.</summary>
    Blocked,
}

/// <summary>One entry of the security log: a suspected attack, or a bug when the names came from code.</summary>
public sealed record SecurityEvent(DateTimeOffset At, string User, string Action, string Kind, string Detail);

/// <summary>The outcome, the call's result when it ran, and the message to show the user (never the detection details).</summary>
public sealed record GuardResult<T>(GuardOutcome Outcome, T? Value, string ForTheUser);

/// <summary>
/// A security check around ARX calls: the pattern to copy into an application, kept small so it can be read in one
/// go. It lets every ARX error through except <c>ARX1017 SuspectedInjection</c>, which it turns into:
/// <list type="bullet">
/// <item>an entry in the security log (<see cref="Events"/>), with the user, the action and ARX's message (the name is
/// escaped and cut to 64 characters by ARX, so it is safe to log);</item>
/// <item>a plain message for the user that doesn't say what was detected;</item>
/// <item>a strike against the user. After <c>blockAfter</c> strikes the user is blocked and their calls aren't attempted.
/// One strike never blocks anyone, so a single false positive only costs one refused request;</item>
/// <item>no strike when the names came from your own code (<see cref="NameSource.Code"/>): that's a bug to fix, logged
/// as one.</item>
/// </list>
/// A false positive (a harmless name such as a file header <c>E-mail (work)</c> flagged as SQL) is handled by triage:
/// read the event, fix the mapping that let the name through, and <see cref="Unblock"/> the user if needed.
/// In a real application the log goes to your SIEM or security monitoring and the strikes live in a shared store
/// (Redis, the database), not in memory.
/// </summary>
public sealed class SecurityGuard
{
    private const string ATTACK = "suspected attack";
    private const string BUG = "bug";

    private readonly object _gate = new();
    private readonly int _blockAfter;
    private readonly Dictionary<string, int> _strikes = new(StringComparer.Ordinal);
    private readonly List<SecurityEvent> _events = new();

    public SecurityGuard(int blockAfter = 3)
    {
        _blockAfter = blockAfter;
    }

    /// <summary>The security log, oldest first.</summary>
    public IReadOnlyList<SecurityEvent> Events
    {
        get
        {
            lock (_gate)
            {
                return _events.ToArray();
            }
        }
    }

    public bool IsBlocked(string user)
    {
        lock (_gate)
        {
            return _strikes.TryGetValue(user, out var strikes) && strikes >= _blockAfter;
        }
    }

    /// <summary>After triage found the events were a false positive: clears the user's strikes (the log is kept).</summary>
    public void Unblock(string user)
    {
        lock (_gate)
        {
            _strikes.Remove(user);
        }
    }

    /// <summary>Runs <paramref name="call"/> for <paramref name="user"/> unless they are blocked, and handles ARX1017 as described above.</summary>
    public async Task<GuardResult<T>> RunAsync<T>(string user, string action, NameSource names, Func<Task<T>> call)
    {
        if (IsBlocked(user))
        {
            return new GuardResult<T>(GuardOutcome.Blocked, default, "Your access is suspended. Contact support.");
        }

        try
        {
            return new GuardResult<T>(GuardOutcome.Done, await call(), "Done.");
        }
        catch (ArxValidationException error) when (error.Code == ArxErrorCode.SuspectedInjection)
        {
            lock (_gate)
            {
                if (names == NameSource.Code)
                {
                    _events.Add(new SecurityEvent(DateTimeOffset.UtcNow, user, action, BUG, error.Message));
                    return new GuardResult<T>(GuardOutcome.Refused, default, "Something went wrong on our side. It has been reported.");
                }

                _strikes[user] = _strikes.GetValueOrDefault(user) + 1;
                _events.Add(new SecurityEvent(DateTimeOffset.UtcNow, user, action, ATTACK, error.Message));
            }

            return new GuardResult<T>(GuardOutcome.Refused, default, "The request couldn't be processed.");
        }
    }
}

  > 1. A normal request passes through
      ana: Done, contact 6af533afbd188482979011b2
  > 2. An attack is logged; the user sees a plain message
      mallory sees: "The request couldn't be processed."
      security log: suspected attack, mallory, create contact
  > 3. Repeated attacks block the user
      mallory blocked: True; a valid request: Blocked, "Your access is suspended. Contact support."
  > 4. A false positive: a harmless file header flagged as SQL
      sam: Refused; blocked: False (one strike blocks nobody)
      triage reads: ARX1017 SuspectedInjection: Attribute name 'E-mail (work)' looks like an SQL injection attempt (contains '('). ARX refused it before sending anything to the database. Names must come from your code or a fixed list, never from user input.
      after the fix: Done, contact 6af533b0bd188482979011b3