Dots

This is a janky, POC CMDB-lite that uses PowerShell, neo4j, and a little duct-tape

WARNING: This is at the maybe sufficient for demo purposes stage. No tests. Many assumptions. Use at your own risk : )

What can Dots do?

Out of the box, we can query external sources for:

• Servers, via
  • Active Directory computer accounts
  • PuppetDB nodes and facts (soon)
• Users, via
  • Active Directory user accounts
• Groups, via
  • Active Directory groups
• Group memberships, via
  • Active Directory

We can also define data where Dots is the source of truth:

• Services i.e. Active Directory, not NTDS
• Service composition i.e. what servers or services make up a service
• Service dependencies i.e. what servers and services does a service depend on

We take all this information, and connect the dots with Neo4j and some sloppy code

How do I get Started?

Initial installation and configuration

• Install neo4j somewhere

  • Chocolatey, docker examples
  • Glenn's references on chocolatey or a Neo4j Enterprise cluster in docker for Windows.
  • Neo4j doesn't require Windows!

• Install and configure Dots

# Install Dots and required modules - powershell-yaml and psneo4j
Install-Module Dots

# Configure PSNeo4j URI
Set-PSNeo4jConfiguration -BaseUri 'http://127.0.0.1:7474' # likely 'http://192.168.99.100:7474' for docker machine, etc.

# Change from the initial neo4j:neo4j creds, save config
$Credential = Get-Credential -UserName neo4j -Message 'Password for user neo4j'
Set-Neo4jPassword -Password $Credential.Password
Set-PSNeo4jConfiguration -Credential $Credential

# Are we connected?
Get-Neo4jUser

# Get details on what we can configure
Get-DotsConfig

Using Dots

# Assumption: You've already Set-PSNeo4jConfiguration to the right BaseUri/credential

Import-Module Dots -Force

# Check the default configs
Get-DotsConfig

# Check Set-DotsConfig, set things as desired.  We'll use mock data via 'TestMode'
Get-Help Set-DotsConfig -Full
Set-DotsConfig -TestMode

# Check what would run by default
Connect-TheDots -Whatif

# Run it!  We prompt for each DotsSources/ExternalSources script unless you -confirm:$False
Connect-TheDots

# Browse the the $BaseUri to explore at the GUI
# User: neo4j, password: $Credential.GetNetworkCredential().Password
$BaseUri

# Explore with cypher and psneo4j

# What labels exist?  Pick one, get all nodes with that label!
Get-Neo4jLabel
Invoke-Neo4jQuery 'MATCH (n:Server) RETURN n'

# Show server-ispartof-service map
Invoke-Neo4jQuery -Query @"
MATCH (s:Server)-[r:IsPartOf]->(svc:Service)
RETURN s.DotsHostname AS ComputerName,
       type(r) AS Relationship,
       svc.name AS ServiceName
"@ -As ParsedColumns | Format-Table -AutoSize

# show service-uses-servers map
Invoke-Neo4jQuery -Query @"
MATCH (s:Server)-[r:IsPartOf]->(svc:Service)
RETURN {
    ServiceName: svc.name,
    Servers: collect(s.DotsHostname)
}
"@ -as Row

# Delete all data, indices, and constraints
Clear-Neo4j

What do I need to configure?

Most configuration involves Get-DotsConfig and Set-DotsConfig

Some things to consider:

• ScriptsPath and DataPath live under the module by default. Move these elsewhere to avoid losing them if you remove or update the module
• You might not have all of the data sources we support by default. Use ScriptsToIgnore to exclude these
• This DotsConfig data is serialized in a file identified via Get-DotsConfigPath
• We heavily use PSNeo4j. You can use Set-PSNeo4jConfiguration and Get-PSNeo4jConfiguration to configure this. At a minimum, you'll need to specify the BaseUri and Credential

Does this support <insert technology>?

This is up to you! Ultimately, Connect-TheDots will run whatever you put in the ScriptsPaths (Danger!)

You might consider:

• Submitting an issue with your idea, including
  • What it should create (nodes, relationships, both)
  • What it creates:
    • Node label, and if label exists, consider a common prefix
    • Relationship type, and ways to identify start and end nodes
  • Whether the data source should be Dots (DotsSources) or external (ExternalSources)
• Borrowing existing code in ExternalSources or DotsSources, adjusting to meet your needs. Or just write it from scratch, my examples are a bit ugly!
• Submitting a pull request!

I'll generally be happy to accept extensions directly to this project, with the caveat that:

• I might be somewhat picky about property names and prefixes, if you're adding to an existing node label
• I might add your script in the default ScriptsToIgnore list if it's a niche data source