Using AsaLib

Getting Started

Getting AsaLib

Search Nuget for Microsoft.CST.AttackSurfaceAnalyzer.

API Documentation

API Documentation is available at https://microsoft.github.io/AttackSurfaceAnalyzer/.

Using AsaLib

Setting up for using the database (optional)

DatabaseManager.Setup(dbPath);

For logging messages (optional)

Logger.Setup(false, true);
Strings.Setup();

Disable telemetry (optional)

AsaTelemetry.Setup(test: true);

Collecting

Collecting using a Delegate (recommended)

You can provide your own Change Handler that will be called on every CollectObject discovered by the Collector.

ConcurrentStack<CollectObject> stack = new ConcurrentStack<CollectObject>();

void MyFunction(CollectObject collectObject) { 
    // Do something with each CollectObject
    // For example, print it out and put it on a stack
    Console.WriteLine($"Found {collectObject.Identity}");
    stack.Push(collectObject);
}

var cc = new CertificateCollector(changeHandler: collectObject => MyFunction(collectObject));
cc.Execute();

In-Memory

You can also perform collections and store the results in the Collector.

For larger collections, for example, full File System or Registry collections, this will consume large amounts of memory. If you can perform actions as results are processed, you should use the Delegate declaration available for each Collector instead.

var cc = new CertificateCollector();
cc.Execute();
ConcurrentStack<CollectObject> results = cc.Results;

Collecting using the ASA Database API

You can also choose to write the results to the database.

The call to DatabaseManager.Write actually adds the result into a queue to be written asynchronously. You must ensure that all results have been written before Committing the results to the database. You can use WaitUntilFlushed() to sleep the main thread until the queue has been flushed.

var cc = new CertificateCollector(changeHandler: collectObject => DatabaseManager.Write(collectObject, RunId));
cc.Execute();

DatabaseManager.WaitUntilFlushed();
DatabaseManager.Commit();

Comparing

From the database

BaseCompare bc = new BaseCompare();
if (bc.TryCompare(FirstRunId, SecondRunId))
{
    ConcurrentDictionary<(RESULT_TYPE, CHANGE_TYPE), List<CompareResult>> results = bc.Results;
}
else
{
    // There was some error while comparing
}

From memory

IEnumerable<CollectObject> FirstRunItems; // Your results from the first collection
IEnumerable<CollectObject> SecondRunItems; // Your results from the second collection

BaseCompare bc = new BaseCompare();
bc.Compare(FirstRunItems, FirstRunItems, FirstRunId, SecondRunId);

ConcurrentDictionary<(RESULT_TYPE, CHANGE_TYPE), List<CompareResult>> results = bc.Results;

Analyzing

Analysis is performed on CompareResult objects from BaseCompare.Compare. The sample code below updates the CompareResults with their analysis status in place.

BaseCompare bc = new BaseCompare();
bc.Compare(DifferentItems,ModifiedItems,FirstRunId,SecondRunId);

Analyzer analyzer = new Analyzer(PLATFORM.WINDOWS, pathToAnalysisFile);

if (analyzer.VerifyRules().Any()){
   // Error With Rules
}
else {
    foreach (var key in bc.Results.Keys)
    {
        if (bc.Results[key] is List<CompareResult> queue)
        {
            queue.AsParallel().ForAll(res =>
            {
                res.Rules = analyzer.Analyze(res);
                res.Analysis = res.Rules.Max(x => x.Flag);
            });
        }
    }
}