+I don't want one bad actor to brick my fleet; I want them to make a pull request first. + +Matt Carr, CPE manager ++ +Fleet's adoption of the GitOps workflow represents a significant advancement in managing device configuration profiles. This modern approach to continuous deployment (CD) uses Git as the central source of truth for declarative infrastructure and application configurations and, now, with our latest update, for MDM configuration profiles across both macOS and Windows platforms. + + +Integrating Windows support into Fleet's MDM adds a new layer of efficiency and cohesion to this workflow. IT administrators can now manage and synchronize MDM configuration profiles for macOS and Windows devices within the same Git repository. This unified approach allows for significant time savings and reduces the complexity of managing multiple platforms. + + +Key to this enhanced workflow is the ability to merge macOS and Windows MDM configuration profiles in a single Git commit. This capability streamlines updating or modifying device profiles across different operating systems. Instead of handling each platform separately, administrators can now consolidate changes, ensuring consistency and reducing potential errors. + + +This unified GitOps workflow also facilitates better collaboration among team members. Changes to MDM profiles, whether for macOS or Windows, can be reviewed, discussed, and approved through the same Git-based processes that software development teams are already familiar with. This approach fosters a transparent, collaborative environment where configuration changes are visible, traceable, and auditable. + + +Moreover, by leveraging Git's robust version control capabilities, Fleet ensures that any changes to MDM profiles are tracked systematically. Administrators can easily roll back to previous configurations if needed, providing a safety net against unintended consequences of changes. + + +Fleet's enhanced GitOps workflow, with its support for merging macOS and Windows MDM configuration profiles in a single commit, represents a significant stride towards simplifying and unifying the management of diverse device environments. This approach streamlines operations and aligns with best software development and deployment practices, enhancing overall IT efficiency and collaboration. + + + + +## Enhance user experience with programmability and automation in Windows MDM + + +Adding Windows MDM support to Fleet further enriches the programmability and automation aspects of the platform. Fleet's API and Command Line Interface (CLI) offer a lot of flexibility for teams to program Fleet according to their specific needs. This flexibility is now extended to Windows environments, ensuring Fleet's capabilities are as effective on Windows as on macOS. + + +Fleet integrates with leading configuration management platforms such as Chef, Ansible, and Puppet. While [Munki](https://github.com/munki/munki) is widely used for macOS, its equivalent in Windows is [Chocolatey](https://chocolatey.org/). Fleet's MDM solution supports both, meaning that from disk encryption with recovery key escrow to configuration profiles for various computer settings, Fleet enables complete curation of the device onboarding experience, irrespective of the operating system. + + + +## User-first transparency + + +In our commitment to a transparent, user-first model, Fleet upholds the principles of clarity and openness, especially by including Windows in our MDM capabilities. As with macOS, Linux, and Chromebooks, Windows users within Fleet's framework can be assured of our steadfast commitment to transparency. Fleet is open source, so users are fully informed about how their employers monitor their work devices. This transparency extends to Windows devices. Fleet software does not intrude on private data such as keystrokes, emails, or webcams but focuses on essential information like user accounts, device health, installed software, and security configurations. Our approach to scope transparency ensures that users understand and can trust how their devices are managed and secured within Fleet's ecosystem, regardless of the operating system. + + + + +## In summary + + +Fleet's expansion to include Windows support in its device management capabilities marks a significant milestone in our mission to simplify and secure MDM across diverse platforms. This integration caters to modern organizations operating in a Windows-dominant environment, filling a crucial gap in the market for a versatile, cross-platform MDM solution. By combining the strengths of MDM with its analytical capabilities, Fleet offers a comprehensive approach to device security and management. The unified GitOps workflow and enhanced programmability and automation features further streamline the management of both macOS and Windows devices, offering a cohesive experience that aligns with modern IT needs. Above all, Fleet maintains its commitment to transparency and a user-first model, ensuring users across all platforms, including Windows, know and trust how their devices are managed within our ecosystem. This update reinforces Fleet's position as a versatile, efficient, and trustworthy device management solution that organizations can rely on in today's varied and dynamic IT landscapes. + + + + + + + diff --git a/articles/fleet-osquery-unlocking-the-value-of-axonius-with-open-source-telemetry.md b/articles/fleet-osquery-unlocking-the-value-of-axonius-with-open-source-telemetry.md new file mode 100644 index 000000000..14d7e3a0d --- /dev/null +++ b/articles/fleet-osquery-unlocking-the-value-of-axonius-with-open-source-telemetry.md @@ -0,0 +1,39 @@ +# Fleet & osquery: Unlocking the value of Axonius with open-source telemetry + + + +In a secure government office, a team of cybersecurity experts monitors a network sprawling across thousands of devices - each a node in a complex web of national security. Their task is daunting: safeguard these digital assets against ever-evolving cyber threats. It's a digital battlefield where visibility and quick response are their best defense. This is the environment where Axonius, coupled with Fleet Device Management powered by osquery, shines as a beacon of innovation and security. + +Amid this high-stakes scenario, Axonius emerges as a cornerstone of asset management and security orchestration. Combined with Fleet Device Management, it is not just an enhancement; it's a transformational shift in managing federal cybersecurity. + + +Fleet, already a trusted tool in organizations like Fastly, brings a suite of functionalities to the Axonius platform. With Axonius providing a comprehensive asset inventory, Fleet elevates this to a new level of security proficiency: + + +* **Enhanced Vulnerability Reporting and Management:** By leveraging osquery-based discovery of all software items on devices and comparing that inventory to the National Vulnerability Database (NVD) and other sources, Fleet provides advanced vulnerability reporting capabilities. Federal agencies can detect and prioritize vulnerabilities in near-real-time. Once the scope of the device fleet is known by Axonius, agencies can track the coverage of the osquery agent used by Fleet to track improvement to overall security posture. +* **Streamlined Device Management (MDM):** Fleet allows organizations to manage their fleet of devices efficiently. With Axonius’s device inventory, MDM enrollment can be tracked accurately, ensuring agencies maximize centralized control over their devices, ensuring proper configurations, secure access, and compliance with security policies. +* **Comprehensive Device Health Monitoring:** Ensuring the health and performance of devices is vital for federal agencies. Fleet monitors the health of devices in real-time, enabling agencies to address issues promptly and minimize security risks. +* **Granular Posture-Based Access Control:** Integrating Fleet's posture-based access control features with Axonius can help agencies enforce security policies dynamically. Devices that meet predefined security standards can gain access, while non-compliant devices are isolated, reducing the attack surface. +* **Optimized Software License Management:** Fleet can identify unused or underutilized software licenses, helping agencies optimize their software assets and reduce costs. When shared with Axonius, this data can be used to track license usage and ensure compliance with software agreements alongside Axonius's other inventory tracking capabilities. + + +Leveraging the open-source power of osquery, Fleet bolsters Axonius’s agency customers to advance threat detection: + + +* **Real-Time Endpoint Visibility:** osquery transforms endpoints into an SQL database, allowing agencies to query endpoints in real time for critical data on system configurations, processes, and user activities. This valuable information can enhance Axonius’s comprehensive asset inventory. +* **Robust Threat Detection:** osquery offers a robust mechanism for detecting threats and anomalies across the endpoint environment. By sharing this data with Axonius, federal agencies can correlate threat information with asset details, facilitating rapid threat response and mitigation. +* **Accelerated Incident Response:** Using osquery alongside Axonius empowers federal agencies to enhance their incident response capabilities. Security teams can swiftly identify compromised endpoints, isolate them, and initiate remediation actions. + + +In the intricate and ever-shifting world of federal cybersecurity, where teams of experts vigilantly guard a network of countless devices, the combination of Axonius with Fleet emerges as a pivotal force. This alliance is not just about enhancing capabilities; it represents a significant leap in how cybersecurity is managed at the federal level. + +With Fleet's robust functionality and Axonius's comprehensive asset management, this partnership extends beyond mere technological advancement. It embodies a strategic shield intricately woven to protect the nation's digital infrastructure against the relentless tide of cyber threats. In this challenging digital battlefield, where clarity and rapid response are paramount, Axonius and Fleet stand as crucial allies, offering a blend of visibility, precision, and agility critical for safeguarding national security interests. + + + + + + + + + diff --git a/articles/fleet-terraform-byo-vpc-module.md b/articles/fleet-terraform-byo-vpc-module.md new file mode 100644 index 000000000..64a55e24b --- /dev/null +++ b/articles/fleet-terraform-byo-vpc-module.md @@ -0,0 +1,295 @@ +# Using the Fleet Terraform module with an existing VPC + +The Fleet Terraform module is the recommended way to quickly get Fleet up and running in AWS. However, some organizations may already have an existing VPC that they would like leverage to deploy Fleet. This article shows what that would look like, leveraging the module at the bring-your-own VPC (BYO-VPC) level. + +## Required resources + +Starting at the BYO-VPC level has all of the same initial [requirements](https://fleetdm.com/docs/deploy/deploy-on-aws-with-terraform#bring-your-own-nothing) as the root (BYO-Nothing) Terraform module. We will need to include these in our example here as well for visibility: + +```hcl + +terraform { + required_providers { + aws = { + source = "hashicorp/aws" + version = "~> 4.0" + } + } +} + +locals { + fleet_domain_name = "fleet.
+changeAtNextAuth (boolean)
+
+If true, the system causes a password reset to occur the next time the user tries to authenticate. If this key is set in a device profile, the setting takes effect for all users, and admin authentications may fail until the admin user password is also reset. Available in macOS 10.13 and later.
+
+
+Another solution is to use Fleet's remote script execution capability to trigger a one-off password reset on the host.
+
+```
+pwpolicy -u "501" -setpolicy "newPasswordRequired=1"
+```
+
+This will require the user to reset their password upon the next login to the host. This is likely the best solution in this situation, as it can be applied on an individual host basis.
+
+In wrapping up this exploration into the intricacies of passcode profiles and their challenges, Fleet's open-source nature allows us to share these experiences and collectively seek solutions that enhance our understanding and implementation of device management policies. Let's continue the conversation. [Join us on Slack](https://fleetdm.com/support) and let us know how you might solve this issue and what device management problems you want to solve.
+
+
+
+
+
+
+
+
+
+
+
diff --git a/articles/the-device-security-tightrope-balancing-cost-and-protection-in-K-12-schools.md b/articles/the-device-security-tightrope-balancing-cost-and-protection-in-K-12-schools.md
new file mode 100644
index 000000000..72d653528
--- /dev/null
+++ b/articles/the-device-security-tightrope-balancing-cost-and-protection-in-K-12-schools.md
@@ -0,0 +1,81 @@
+# The device security tightrope: balancing cost and protection in K-12 schools
+
+
+
+In today's digital classrooms, the diversity of devices and operating systems—from Macs and Windows to Linux and Chromebooks—presents unique challenges for K-12 schools. As technology becomes increasingly integral to education, the complexity of managing cybersecurity risks grows. The task is daunting: ensuring robust protection against cyber threats while grappling with limited budgets and IT resources. In August 2023, the [U.S. Department of Education highlighted these challenges](https://www.ed.gov/news/press-releases/department-of-education-announces-k-12-cybersecurity-resilience-efforts), emphasizing the need for schools to balance cost with effective cybersecurity measures. This blog post delves into the evolving landscape of digital education, exploring strategies for K-12 schools to navigate the precarious balance between securing their digital infrastructure and managing costs efficiently. Drawing on recent governmental efforts and expert insights, we'll outline actionable steps to lead to a more secure and enriching learning environment for all.
+
+
+## The growing cybersecurity challenge in education
+
+In August 2023 U.S. Department of Education posted a press release, “[Key K-12 Cybersecurity Resilience Efforts](https://www.ed.gov/news/press-releases/department-of-education-announces-k-12-cybersecurity-resilience-efforts),” discussing the growing security challenges for educational institutions. U.S. Secretary of Education Miguel Cardona is quoted as saying,
+
+Let’s face it: in today’s digital age, our students and their teachers will increasingly use technology in the classroom. Schools have access to more devices and connectivity than ever before, and this technology in education has incredible potential to help students better connect with their learning and achieve, and teachers better engage with their students. But to make the most of these benefits, we must effectively manage the risks. Just as we expect everyone in a school system to plan and prepare for physical risks, we must now also ensure everyone helps plan and prepare for digital risks in our schools and classrooms. The Department of Education has listened to the field about the importance of K-12 cybersecurity, and today we are coming together to recognize this and indicate our next steps. ++ + +## National attention on cybersecurity in schools + +Even the White House is showing concerns. In August 2023, the White House sponsored The White House’s Back to School Safely: Cybersecurity Summit for K-12 Schools. They discussed the challenges educators, students, and families face in this increasing number of devices schools have to support, as well as the publication by the Department's Office of Educational Technology and CISA titled "K-12 Digital Infrastructure Brief: Defensible and Resilient." Key considerations include: + + + + + +* **Enhancing continuous risk management:** Addressing the ever-evolving threat landscape by proactively managing cybersecurity risks. +* **Utilizing analogies for understanding:** Leveraging lessons from physical world scenarios to comprehensively grasp and tackle cybersecurity challenges. +* **Prioritizing and implementing mitigation strategies:** Identifying the most critical risks and applying effective mitigations such as multi-factor authentication, robust password policies, phishing prevention, and regular software updates. +* **Building resilience for cyber incidents:** Developing and practicing cyber incident response plans to minimize the impact of potential cybersecurity breaches. +* **Vendor engagement for enhanced security:** Encouraging vendors to invest in secure design principles, obtain cyber risk assurance certifications, and establish security vulnerability disclosure practices. + + +## The overlooked factor: balancing cost and security + +Juan Hernandez's article in [The Prey Project in August 2023](https://preyproject.com/blog/device-security-policies-it-schools) discusses why device management is essential for K-12 schools. Hernandez’s article doesn’t address one of the most significant factors, cost. Today K-12 schools struggle with tight budgets, lack of technical resources, and overworked IT and educator staff require school districts to walk a tightrope between cost and risk. Below are a few considerations designed to help schools with this balancing act. + + +## Strategies for cost-effective cybersecurity in schools + + + +* **Embrace open-source:** Consider open-source solutions for their affordability, agility, and strong community support. +* **Cost-effectiveness:** Explore solutions that replace redundant, unused tools and avoid vendor lock-in. +* **Converge IT solutions:** Integrate tools and processes into IT operations for a holistic approach. +* **Consolidate and automate tasks:** Integrate and automate IT operations to reduce redundancy and free up staff for strategic initiatives. +* **Prioritize updates:** Act fast on critical patches to minimize vulnerabilities. Be intentional about what you patch. Focus on known exploits and vulnerabilities that exist in your environment first. +* **Implement endpoint protection:** Defend against cyber threats like ransomware to safeguard sensitive data. +* **User education:** Empower users with cybersecurity awareness training and offer transparency about data collection to build trust. + + +## Additional considerations for a comprehensive approach to cybersecurity + + + +* **Compliance:** Ensure adherence to data privacy regulations like COPPA, FERPA, and GDPR. +* **Continuous adaptation:** Regularly evaluate and adapt your security posture to stay ahead of evolving threats. + + +## Creating a secure and affordable digital learning environment + +In navigating the complex landscape of device security in K-12 schools, it's clear that a balanced approach is not just beneficial; it's necessary. Schools can protect their digital environments by integrating cost-effective strategies with robust cybersecurity measures without straining their budgets. As we've explored, this involves embracing open-source solutions, prioritizing critical updates, and fostering a culture of cybersecurity awareness among all users. + +We understand that every school's situation is unique, with its specific challenges and resources. Therefore, we encourage educational institutions to consider and adapt the strategies discussed here to fit their unique circumstances. Implementing these practices may require time and effort, but the payoff in enhanced security and peace of mind is invaluable. + + +## Let's start a conversation + +How does your school balance the demands of cybersecurity with budget limitations? Have you found innovative solutions or faced particular challenges in this journey? Share your stories, questions, and insights with us. Your experiences enrich our collective understanding and contribute to building a resilient, informed, and supportive community around the critical issue of K-12 cybersecurity. + +Join the dialogue in our community [Fleet Slack channels](https://fleetdm.com/support) to exchange ideas, ask questions, and connect with peers navigating similar challenges. Your input is vital in shaping effective and sustainable cybersecurity practices in education. + +Together, we can create safer digital spaces for our students and educators, ensuring that technology remains a powerful tool for learning and growth, not a vulnerability. + + + + + + + + + + + diff --git a/articles/understanding-the-intricacies-of-fleet-policies-host-policy-view-1818x1999@2x.png b/articles/understanding-the-intricacies-of-fleet-policies-host-policy-view-1818x1999@2x.png new file mode 100644 index 000000000..0b2a57a90 Binary files /dev/null and b/articles/understanding-the-intricacies-of-fleet-policies-host-policy-view-1818x1999@2x.png differ diff --git a/articles/understanding-the-intricacies-of-fleet-policies.md b/articles/understanding-the-intricacies-of-fleet-policies.md new file mode 100644 index 000000000..4cd781e91 --- /dev/null +++ b/articles/understanding-the-intricacies-of-fleet-policies.md @@ -0,0 +1,77 @@ +# Understanding the intricacies of Fleet policies + + + +In the ever-evolving landscape of device management and cybersecurity, understanding the mechanics behind tools like Fleet is not just about technical curiosity; it's about empowering IT professionals to safeguard digital assets more effectively. [Fleet](https://fleetdm.com) gathers telemetry from various devices, from laptops to virtual machines, using [osquery](https://www.osquery.io/). At the heart of this system lies a crucial feature: [Fleet policies](https://fleetdm.com/securing/what-are-fleet-policies). + +Policies in Fleet are more than just rules; they are the gatekeepers of your device's security, ensuring stringent adherence to security standards. By dissecting how Fleet policies operate "under the hood," IT administrators and security professionals can gain invaluable insights. These insights allow for setting up efficient security protocols and rapid response to potential vulnerabilities, a necessity in a landscape where cyber threats are constantly evolving. This article delves into the inner workings of Fleet policies, providing you with the knowledge to better configure, manage, and leverage these policies for optimal device security and efficiency. + + +## Policy creation + +Policies can be created from the web UI, the command-line interface called `fleetctl` with config files, or the REST API. The user creates a policy and selects which devices need to be checked using that policy. Policies can be global or team-specific. + +When a policy is created, a record for it is stored in the **policies** table of the MySQL database. A Fleet deployment consists of several servers behind a load balancer, so storing the record in the DB makes all servers aware of the new policy. + + + + + + +## Policy execution + +Policies are executed on the devices, which are called **hosts** in Fleet, according to the [FLEET_OSQUERY_POLICY_UPDATE_INTERVAL](https://fleetdm.com/docs/configuration/fleet-server-configuration#osquery-policy-update-interval), which is set to 1 hour by default. This interval can be adjusted with the environment variable or set from the server’s command line. + +Policies are simply SQL queries that return a true or false result, so the flow they use on the hosts is the same as other queries. Hosts check in with Fleet servers every 10 seconds (the default) and access the `/api/v1/osquery/distributed/read` API endpoint. The server checks when the policy was last executed to determine whether it should be executed again. If so, the server adds the policy to its response. For example, this policy in the server response checks if the macOS firewall is enabled: + + +``` +{ + "queries": { + "fleet_policy_query_9": "SELECT 1 FROM alf WHERE global_state >= 1;" + }, + "discovery": { + "fleet_policy_query_9": "SELECT 1" + } +} +``` + + +Once the host has executed the policy, it writes the result to the server. The server updates the result in the **policy_membership** table of the MySQL database. At this point, the Host Details page on the web UI is updated with the policy result. + + + + + + +## Force policy execution on a device + +The user can force the host to execute all of its policies by clicking the **Refetch** link: + + + + + +## Policy results aggregation + +However, the main **Policies** page is not updated. This page shows the counts of all passing and failing hosts for each policy. A worker process on one of the Fleet servers updates it once an hour. The worker calculates the counts and stores them in the **policy_stats** table in the database. This is done for better performance of the UI. For customers with 100,000s of hosts that asynchronously report their policy results, calculating the passing and failing counts in real time was noticeably slow. + + + + + + +## Summary + +Understanding the intricacies of Fleet policies is essential for IT professionals managing a fleet of devices. This deep dive into the mechanics of Fleet policies — from creation to execution — provides you with the necessary insights to optimize your cybersecurity strategy effectively. By leveraging these policies, you can ensure stringent security standards across your network, enhancing your organization's digital defense. As the cyber landscape evolves, tools like Fleet remain crucial in maintaining robust and responsive security protocols. We encourage you to apply these insights in your Fleet usage, and as always, we welcome your feedback and experiences in the [Fleet community Slack channels](https://fleetdm.com/support). + + + + + + + + diff --git a/articles/using-fleet-and-tines-together.md b/articles/using-fleet-and-tines-together.md index 11169e431..5c2353168 100644 --- a/articles/using-fleet-and-tines-together.md +++ b/articles/using-fleet-and-tines-together.md @@ -74,8 +74,6 @@ The final email with the above definition looks like this: The Fleet API is very flexible, but with the addition of Tines, the options for data transformation are endless. In the above example, we easily connected to the Fleet API and transformed the data response with a single Tines Transform function, and allowed the end user to receive a customized report of vulnerable software on an individual host. -
Running with systemd
+ +This content was moved to [Systemd](http://fleetdm.com/docs/deploy/system-d) on Sept 6th, 2023. + +Using a proxy
+ +This content was moved to [Proxies](http://fleetdm.com/docs/deploy/proxies) on Sept 6th, 2023. + +Configuring single sign-on (SSO)
+ +This content was moved to [Single sign-on (SSO)](http://fleetdm.com/docs/deploy/single-sign-on-sso) on Sept 6th, 2023. + +Public IPs of devices
+ +This content was moved to [Public IPs](http://fleetdm.com/docs/deploy/public-ip) on Sept 6th, 2023. + + + + diff --git a/docs/Contributing/API-Versioning.md b/docs/Contributing/API-Versioning.md index 32aa06626..8dc8deeb1 100644 --- a/docs/Contributing/API-Versioning.md +++ b/docs/Contributing/API-Versioning.md @@ -107,3 +107,4 @@ This will mean that the following are the only valid paths after this point: And the code doesn't have to specify `.StartingAtVersion("2021-12")` anymore. + diff --git a/docs/Contributing/API-for-contributors.md b/docs/Contributing/API-for-contributors.md index a4512f1d6..f46c32cdd 100644 --- a/docs/Contributing/API-for-contributors.md +++ b/docs/Contributing/API-for-contributors.md @@ -8,10 +8,13 @@ - [Device-authenticated routes](#device-authenticated-routes) - [Downloadable installers](#downloadable-installers) - [Setup](#setup) +- [Scripts](#scripts) -This document includes the Fleet API routes that are helpful when developing or contributing to Fleet. +This document includes the internal Fleet API routes that are helpful when developing or contributing to Fleet. -Unlike the [Fleet REST API documentation](https://fleetdm.com/docs/using-fleet/rest-api), only the Fleet UI, Fleet Desktop, and `fleetctl` clients use the API routes in this document: +These endpoints are used by the Fleet UI, Fleet Desktop, and `fleetctl` clients and will frequently change to reflect current functionality. + +If you are interested in gathering information from Fleet in a production environment, please see the [public Fleet REST API documentation](https://fleetdm.com/docs/using-fleet/rest-api). ## Packs @@ -526,11 +529,12 @@ The MDM endpoints exist to support the related command-line interface sub-comman - [Generate Apple DEP Key Pair](#generate-apple-dep-key-pair) - [Request Certificate Signing Request (CSR)](#request-certificate-signing-request-csr) -- [Batch-apply Apple MDM custom settings](#batch-apply-apple-mdm-custom-settings) +- [Batch-apply MDM custom settings](#batch-apply-mdm-custom-settings) - [Initiate SSO during DEP enrollment](#initiate-sso-during-dep-enrollment) - [Complete SSO during DEP enrollment](#complete-sso-during-dep-enrollment) - [Preassign profiles to devices](#preassign-profiles-to-devices) - [Match preassigned profiles](#match-preassigned-profiles) +- [Get FileVault statistics](#get-filevault-statistics) ### Generate Apple DEP Key Pair @@ -544,7 +548,7 @@ None. ##### Default response -``` +```json { "public_key": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNzVENDQVptZ0F3SUJBZ0lCQVRBTkJna3Foa2lHOXcwQkFRc0ZBREFTTVJBd0RnWURWUVFERXdkR2JHVmwKZEVSTk1CNFhEVEl5TVRJeE16RTFNREl6TmxvWERUSXpNREV4TWpFMU1USXpObG93RWpFUU1BNEdBMVVFQXhNSApSbXhsWlhSRVRUQ0NBU0l3RFFZSktvWklodmNOQVFFQkJRQURnZ0VQQURDQ0FRb0NnZ0VCQU1jbXIxOVNiQUhaCnVZNnJBa254dVBCV0tkSFlrSXpJY2JGMHErZ0ZKZVU3cUlwU0FQWFhmeUpFTXpyQXhpZStPSi9QSXhkTHZTZVoKdXA2Qzg5VHM1VEwrWjhKZmR3T2ZLQVFIUWpyQVpGZkxkdUh0SjNRZnk3di9rbmZ3VzNNSU9XZ00zcDQ3a0xzOAowZnJzNmVuTlpXZElsNUMyV1NpOXVGVVVQcFJTbm1Ha1AvK2QydmNCaWdIOHQ0K3RuV3NYdjhpekxqcHhhanV6CjN0Vlp3SFA0cjBQZTdIM0I0eDZINmlKZmxRZzI4Z3owbDZWa0c2NjVKT2NMLzlDSmNtOWpWRmpxb0RmZTVjUFAKMVFNbFpyb1FCaFhOUHN3bEhRWTkzekJFK3VSRUVNL1N1d0dZcGZLYjQwSDM0S1B1U3Y5SXZHTjIzTXdNM01FMwppNEFBWGJQOGZNTUNBd0VBQWFNU01CQXdEZ1lEVlIwUEFRSC9CQVFEQWdXZ01BMEdDU3FHU0liM0RRRUJDd1VBCkE0SUJBUUM5ZFcyRXBxemp1VWhhbk1CSXJpK09VWVhrekR2eVB6bGxTMXd0UVdQQ0s4cFJ5Rk5TM3RkakVXT2kKSTcyOVh2UmtpNjhNZStqRlpxSkxFWHpWUlkwb29aSWhhcG5lNUZoNzlCbkIrWGl6TFQ0TStDNHJ5RVQwOXg4SQpaWHJuY1BKME9ueUdVemlFK0szWEI2dVNLeWN1a3pZci9sRVBBMGlQRTZpM0dNYjljenJFL2NOQURrRXZwcjU2CjN1SFdMU3hwK1U5QmJyaTNDSXBoR1NvSWxnTVBEaUE1RkpiOXc0SnlMK0crZ3Q4c1BlcUZkZDYyRDRpV3U5a0wKMVZBUjRSU2xPcWt1cTVXREZVcUxsVGJFMS9oY1lqcVVUczRrSWhENmN6MkcxQlBnMUU2WVpRZWp6U0ZpeGR1MApYUy9UTTByUFBKNithUC82V1BNRWpJcGVRcmNvCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K", "private_key": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBeHlhdlgxSnNBZG01anFzQ1NmRzQ4RllwMGRpUWpNaHhzWFNyNkFVbDVUdW9pbElBCjlkZC9Ja1F6T3NER0o3NDRuODhqRjB1OUo1bTZub0x6MU96bE12NW53bDkzQTU4b0JBZENPc0JrVjh0MjRlMG4KZEIvTHUvK1NkL0JiY3dnNWFBemVuanVRdXp6Uit1enA2YzFsWjBpWGtMWlpLTDI0VlJRK2xGS2VZYVEvLzUzYQo5d0dLQWZ5M2o2MmRheGUveUxNdU9uRnFPN1BlMVZuQWMvaXZROTdzZmNIakhvZnFJbCtWQ0RieURQU1hwV1FiCnJya2s1d3YvMElseWIyTlVXT3FnTjk3bHc4L1ZBeVZtdWhBR0ZjMCt6Q1VkQmozZk1FVDY1RVFRejlLN0FaaWwKOHB2alFmZmdvKzVLLzBpOFkzYmN6QXpjd1RlTGdBQmRzL3g4d3dJREFRQUJBb0lCQUZRMUFFeGU3bnB0MUc4RgowZ2J3SlpIQjdSYms2bUlNMHo0RXBqZUtEYmI2M2MzMjFKOGV5b3Z6cUhHOFYwMHd1b0tnTkNkQ2lDMjVhOVpnCmFyZHFuNU5MVFJZOEJYZkxrVUQ2ekw5STRHVGJERjZGUjN4cmdWcnh1cjNxTE5EYjltSVBwd1hqQzlTUDUvMmcKdFZ0OTFOV3lOUndrYmxpeXQ4R0p1TmhBZ3VXbnJLQmw5b3o1QkpCU3JLZTJPUE5ERm5mbUs1NFM1VzRKakZZMApFTUV3Z2ZiL2xQZjluWFZwRG9QeEl3QnJmRU5oU3oxcVI0bzJPbVFyRGNOQUNZU05razRjbXVIMHpxc3J5aFg4CkNhajhCcllOemxaeGNPTmpmK1NxUkdvVndjdzZKbzNKazBEREZHeEVaOHBEUThJTXgzRUQ1SE4rbW1SaGRMQmoKT0pRZVhVRUNnWUVBeWZDaFArSVNzMGNtcEM3WUFrK1UrVHNTTElnY3BTTHdReFF2RGFmRWFtMHJoWDJQdDk1ZgpJN1NCTlM3TmlNR0xCVk4rWHg0RHlsT3RYaGNzTm5YUU5qU3J3ZFNHTGxFbU5wWDJXR0x4Znp4REVVbFFSS3FEClY2RHBDaHdmY2tCTFRUNkVaRDlnV21DOGZIYUNPc0JDUHR1VStLQUpFa1FRaVk1VlRLSjYrMkVDZ1lFQS9IYnQKKzIvWFJzSW84VkE4QmhjMitDYyt4YUNrK3dvTVByZ0d4OWxrMTR2R0hDcCtDY2ZGZThqU2NHMDhzU3RKTnJCVgp0cHgvbm1yYklyMzUxVkxlMFNLQ2R2aHF5ajBXQWlWVDhDL0VjcUxGV0VwNG5mY1ZnVHIxRjBGMUptR0Y4WVNYCk41VEh4Tnc4VjZLUDVmWEM2dVVFMkNpZnR1bkxqSGFSNXZCakxxTUNnWUVBdlNjTE0zYUVRNjlTejVrZE5sVHEKMnVUczZnOTRuV256bVRGdnZaKzJ5R1dIelp0R0lsbEZ6b0VHUWhXYjZndzROdjMxTWcxQVNhVkZrQXV1bXppUgpsaVNSK1pZak5ZRkhoUHZFNnhlSzA3NVRwLzUvRkVLUGttWWp3eGVDa1JjT01jVnNaeVpDRDRYcko3NHR6L0JFClhQSjdRTU5PbS9CcmVSMThZck1TOVNFQ2dZQjhqZnhaV1ZNL1FKbE1mTVl3UnhIQ21qSVk5R21ReE9OSHFpa0cKUGhYSFZkazJtaXcyalEyOFJWYTFTdDl2bFNoNHg4Ung1SUg5MlVBbHdzNVlWWnRDV0tFL0tzNGMyc2haNUtxbAp6QnRDWjFXdmVvWkpnTlptUEgwZ3JSV3NDdDgzU2JBRkp1enNEYS9qbUhzZi9BRGZQSUFJV1BwN0ZwdHF3REM1ClhBM0N1d0tCZ0c0QVVmMUZralNYRFBlL2JoVjhtZG4rZCtzN2g2RjZkRWttNnEya1dyS1B4V2lFdlN3QlZEQWoKQjhIRlNtNW1pcHNTTXhQbFVEZDRPSXRSUzVUM1AwcStRZENZNkwzemhmSFBCUzdhTlZaRUJXdVNlY2lDRk0wSQo3MjFSK081TitMTlFwN1N6VWUxRll1WWdhandFSE9KMW82d1ArZWloMmQyVVQyQ09Ed1NrCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==" @@ -570,7 +574,7 @@ Note that the `public_key` and `private_key` are base64 encoded and should be de ##### Default response -``` +```json { "apns_key": "aGV5LCBJJ20gc2VjcmV0Cg==", "scep_cert": "bHR5LCBJJ20gc2VjcmV0Cg=", @@ -582,24 +586,25 @@ Note that the response fields are base64 encoded and should be decoded before wr Once base64-decoded, they are PEM-encoded certificate and keys. -### Batch-apply Apple MDM custom settings +### Batch-apply MDM custom settings -`POST /api/v1/fleet/mdm/apple/profiles/batch` +`POST /api/v1/fleet/mdm/profiles/batch` #### Parameters | Name | Type | In | Description | | --------- | ------ | ----- | --------------------------------------------------------------------------------------------------------------------------------- | -| team_id | number | query | _Available in Fleet Premium_ The team ID to apply the custom settings to. Only one of team_name/team_id can be provided. | -| team_name | string | query | _Available in Fleet Premium_ The name of the team to apply the custom settings to. Only one of team_name/team_id can be provided. | +| team_id | number | query | _Available in Fleet Premium_ The team ID to apply the custom settings to. Only one of `team_name`/`team_id` can be provided. | +| team_name | string | query | _Available in Fleet Premium_ The name of the team to apply the custom settings to. Only one of `team_name`/`team_id` can be provided. | | dry_run | bool | query | Validate the provided profiles and return any validation errors, but do not apply the changes. | -| profiles | json | body | An array of strings, the base64-encoded .mobileconfig files to apply. | +| profiles | json | body | An array of objects, consisting of a `profile` base64-encoded .mobileconfig (macOS) or XML (Windows) file, `labels` array of strings (label names), and `name` display name (only for Windows configuration profiles). | -If no team (id or name) is provided, the profiles are applied for all hosts (for _Fleet Free_) or for hosts that are not part of a team (for _Fleet Premium_). After the call, the provided list of `profiles` will be the active profiles for that team (or no team) - that is, any existing profile that is not part of that list will be removed, and an existing profile with the same payload identifier as a new profile will be edited. If the list of provided `profiles` is empty, all profiles are removed for that team (or no team). + +If no team (id or name) is provided, the profiles are applied for all hosts (for _Fleet Free_) or for hosts that are not assigned to any team (for _Fleet Premium_). After the call, the provided list of `profiles` will be the active profiles for that team (or no team) - that is, any existing profile that is not part of that list will be removed, and an existing profile with the same payload identifier (macOS) as a new profile will be edited. If the list of provided `profiles` is empty, all profiles are removed for that team (or no team). #### Example -`POST /api/v1/fleet/mdm/apple/profiles/batch` +`POST /api/v1/fleet/mdm/profiles/batch` ##### Default response @@ -621,7 +626,7 @@ None. ##### Default response -``` +```json { "url": "https://idp-provider.com/saml?SAMLRequest=...", } @@ -671,12 +676,13 @@ This endpoint stores a profile to be assigned to a host at some point in the fut #### Parameters -| Name | Type | In | Description | -| ------------ | ------ | ---- | ----------------------------------------------------------- | -| external_host_identifier | string | body | **Required**. The identifier of the host as generated by the external service (e.g. Puppet). | -| host_uuid | string | body | **Required**. The UUID of the host. | -| profile | string | body | **Required**. The base64-encoded .mobileconfig content of the MDM profile. | -| group | string | body | The group label associated with that profile. This information is used to generate team names if they need to be created. | +| Name | Type | In | Description | +| ------------ | ------- | ---- | ----------------------------------------------------------- | +| external_host_identifier | string | body | **Required**. The identifier of the host as generated by the external service (e.g. Puppet). | +| host_uuid | string | body | **Required**. The UUID of the host. | +| profile | string | body | **Required**. The base64-encoded .mobileconfig content of the MDM profile. | +| group | string | body | The group label associated with that profile. This information is used to generate team names if they need to be created. | +| exclude | boolean | body | Whether to skip delivering the profile to this host. | #### Example @@ -689,7 +695,8 @@ This endpoint stores a profile to be assigned to a host at some point in the fut "external_host_identifier": "id-01234", "host_uuid": "c0532a64-bec2-4cf9-aa37-96fe47ead814", "profile": "Owner]; + end + + subgraph Agent + orbit[orbit]; + desktop[Fleet Desktop
Tray App]; + osqueryd[osqueryd]; + desktop_browser[Fleet Desktop
from Browser]; + end + + subgraph Customer Cloud + fleet_server[Fleet
Server]; + db[DB]; + redis[Redis
Live queries' results
go here]; + prometheus[Prometheus Server]; + end + + subgraph FleetDM Cloud + tuf["TUF file server
(default: tuf.fleetctl.com)"]; + datadog[DataDog metrics] + heroku[Usage Analytics
Heroku] + log[Send logs to optional
external location] + end + + subgraph Customer Admin + frontend[API user UI or other] + end + + + fleet_release_owner -- "Release Process" --> tuf; + + orbit -- "Fleet Orbit API (TLS)" --> fleet_server; + orbit -- "Auto Update (TLS)" --> tuf; + desktop -- "Fleet Desktop API (TLS)" --> fleet_server; + osqueryd -- "osquery
remote API (TLS)" --> fleet_server; + desktop_browser -- "My Device API (TLS)" --> fleet_server; + + heroku -- "Metrics from all customers" --> datadog; + + fleet_server <== "Read/Write" ==> db; + fleet_server <== "Read/Write" ==> redis; + redis <==> db; + + prometheus ==> fleet_server; + fleet_server -- "metrics" --> heroku; + fleet_server -- "queries results" --> log; + + frontend <== "API" ==> fleet_server; + +``` + + + +## The path of Live Query + +### 1 - Fleet User initiates the query +```mermaid +graph LR; + it_person[Fleet User
Starts a live query]; + api[API Client Frontend or Fleetctl]; + + subgraph Cloud + server(Server); + dbredis[DB / Redis]; + end + + it_person --> api; + api --> it_person; + + api <-- "1 - Initiate Campaign. Get ID" --> server; + api <-- "2 - Register to notifications with ID" --> server; + api <-- "WEB SOCKET" --> server; + server <-- Notifications --> dbredis; + +``` + +### 2 - Agent returns results +```mermaid +graph LR; + osquery[osquery agent]; + + subgraph Cloud + server(Server); + dbredis[DB / Redis]; + end + + osquery -- 1 ask for queries --> server; + osquery -- 2 return results --> server; + + server <-- 1 return queries if found --> dbredis; + server -- 2 put results in Redis --> dbredis; + +``` + +## The path of a scheduled Query + +### 1 - Fleet User initiates the query +```mermaid +graph LR; + it_person[Fleet User
Creates a scheduled
for a team / global]; + api[API Client Frontend or Fleetctl]; + + subgraph Cloud + server(Server); + db[DB]; + end + + it_person --> api; + api --> server; + server -- Query stored in DB--> db; +``` +### 2 - Agent gets config file (with the scheduled query) +```mermaid +graph LR; + agent[Osquery Agent]; + + subgraph Cloud + server(Server); + db[DB]; + end + + agent -- request download config file --> server; + agent <-- teams and global cfg are merged --> server; + server -- ask for cfg file--> db; +``` + +### 3 - Agent returns results to be (optionally) logged +```mermaid +graph LR; + agent[Osquery Agent
Runs query and sends results]; + + subgraph Cloud + server(Server); + log[Optional External Log
e.g. S3]; + end + + agent --> server; + server --> log; +``` + + +## Agent config options +1 - Config TLS refresh +(Typical period 10 secs) OSQuery pulls down a config file that includes instructions for Scheduled Queries. +If both GLOBAL and TEAM is configured, there will be a config merge done on the Server side. + +2 - Logger TLS +(Typical period10 secs) Frequency of sending the results. (different than the frequency of running the queries) +To be improved: Currently the config file gets downloaded every time even if no change was done. + +3 - Distributed (Typical interval 10 sec) +(Typical period10 secs) OSQuery asks for any Live query to run. + + +## Vulnerability dashboard +Typically hosted on our Heroku servers. +Could be hosted on customer servers. +Uses the Fleet server Token to access specific APIs that give information about vulnerability +status. + +### Vuln dashboard hosted by FleetDM +```mermaid +graph LR; + frontend[Frontend on web browser]; + + subgraph Customer Cloud + fleetServer(Fleet Server); + end + + subgraph Heroku Cloud + vulnServer(Vuln Web Server); + end + + frontend --> vulnServer; + vulnServer --> fleetServer; +``` + + \ No newline at end of file diff --git a/docs/Contributing/set-up-custom-end-user-email.md b/docs/Contributing/set-up-custom-end-user-email.md new file mode 100644 index 000000000..8cdd4d18c --- /dev/null +++ b/docs/Contributing/set-up-custom-end-user-email.md @@ -0,0 +1,43 @@ +# Provide end user email address w/o relying on end user + +In issue #15057, we introduced a feature primarily intended for internal use +that allows the specification of the email for the "Used by" field on the host +details page. This feature supports macOS and Windows, but the method to define +the email differs for each operating system. + +### macOS via configuration profiles + +When `fleetd` starts in macOS, it'll check for the user email in the enrollment profile. + +The enrollment profile contains multiple `
enroll_secret, hardware_uuid, etc. + server-->>-orbit: orbit_node_key + + loop every 30 seconds + orbit->>+server: POST /api/fleet/orbit/config
orbit_node_key + server-->>-orbit: pending notifications + end + + note over orbit: Receive enrollment notification
needs_programmatic_windows_mdm_enrollment
windows_mdm_discovery_endpoint + orbit->>windows: mdmregistration.dll
RegisterDeviceWithManagement
discovery endpoint, node key + + windows->>+server: POST /api/mdm/microsoft/discovery + server-->>-windows: EnrollmentServiceURL, EnrollmentPolicyServiceUrl + + windows->>+server: POST /api/mdm/microsoft/policy
DeviceEnrollmentUserToken (node key) + server-->>-windows: Policy Schema, Certificate requirements + activate windows + note left of windows: Generate keypair + deactivate windows + windows->>+server: POST /api/mdm/microsoft/enroll
Self-signed CSR & cert values, DeviceID
DeviceEnrollmentUserToken (node key) + note right of server: Creates certificate signed by WSTEP ident key + server-->>-windows: Signed certificate, management endpoint, enrollment parameters + + loop SYNCML MDM Protocol (mTLS) + windows->>+server: POST /api/mdm/microsoft/management
DeviceID + server-->>-windows: Response + end +``` + +# Glossary + +## WSTEP + +[WSTEP](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-wstep/ac55b8cc-9ade-4982-b135-991d574ade74) is the protocol Microsoft uses to automate certificate requesting and singing. It is similar to the SCEP process used by macOS. + +The certificate created through the WSTEP process is used to authenticate mTLS between the host and management endpoint. + +## SyncML + +[SyncML](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-wstep/ac55b8cc-9ade-4982-b135-991d574ade74) is an XML dialect used by Microsoft for Device Management. + +## mTLS + +[Mutual Transport Layer Security](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/) is a method for securing communications between two parties, in which both parties present signed certificates. This is different from standard TLS, where only the most provides a certificate. This allows both parties to authenticate the other's identity. + +## MDM Protocol Summary + +https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-mdm/33769a92-ac31-47ef-ae7b-dc8501f7104f + +## MDM Device Registration Summary + +https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-dvrd/296ebf70-bd4b-489e-a531-460d8ef7519b + +# Registry + +- `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Enrollments\` + Each enrollment gets its own subdirectory with a UUID as a key, + inside each directory is a set of keys associated with that enrollment + - `CurCryptoProvider` + Often `Microsoft Software Key Storage Provider` + Cryptographic Key storage provider + - `CurKeyContainer` + Key within key provider + - `DiscoveryServiceFullURL` + MDM Discovery service URL + - `DMPCertThumbPrint` + According to [this blog post](https://call4cloud.nl/2022/10/fullmetal-certificate-the-revenge-of-renewal/), this is the thumbprint of your MDM device certificate + - `EnrollmentFlags` + See [this link](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-xcep/cd22d3a0-f469-4a44-95ed-d10ce4dc2063) for details + + | Integer value | Meaning | + |---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | 0x00000001 | Instructs the client and CA to include an S/MIME extension, as specified in [RFC4262]. | + | 0x00000008 | Instructs the CA to append the issued certificate to the userCertificate attribute, on the user object in Active Directory. | + | 0x00000010 | Instructs the CA to check the user's userCertificate attribute in Active Directory, as specified in [RFC4523], for valid certificates that match the template enrolled for. | + | 0x00000040 | This flag instructs clients to sign the renewal request using the private key of the existing certificate. For more information, see [MS-WCCE] section 3.2.2.6.2.1.4.5.6. This flag also instructs the CA to process the renewal requests as specified in [MS-WCCE] section 3.2.2.6.2.1.4.5.6. | + | 0x00000100 | Instructs the client to get a user's consent before attempting to enroll for a certificate based on the specified template. | + | 0x00000400 | Instructs the client to delete any expired, revoked, or renewed certificate from the user's certificate stores. | + | 0x00002000 | This flag instructs the client to reuse the private key for a smart card–based certificate renewal if it is unable to create a new private key on the card. | + - `EnrollmentState` + The best documentation we can find is [here](https://learn.microsoft.com/en-us/graph/api/resources/intune-shared-enrollmentstate?view=graph-rest-beta) + + | Member | Value | Description | + |--------------|-------|--------------------------------------------------------------------------------------------------------------------| + | unknown | 0 | Device enrollment state is unknown | + | enrolled | 1 | Device is Enrolled. | + | pendingReset | 2 | Enrolled but it's enrolled via enrollment profile and the enrolled profile is different from the assigned profile. | + | failed | 3 | Not enrolled and there is enrollment failure record. | + | notContacted | 4 | Device is imported but not enrolled. | + | blocked | 5 | Device is enrolled as userless, but is blocked from moving to user enrollment because the app failed to install. | + + - `EnrollmentType` + According to [this PDF](https://winprotocoldoc.blob.core.windows.net/productionwindowsarchives/MS-MDE2/%5BMS-MDE2%5D.pdf) it can have three different values. + + Device, Full, and AppManaged + + From what I've seen, value 6 on AAD, 1 on manual + - `isFederated` + According to [this web page](https://learn.microsoft.com/en-us/windows/client-management/federated-authentication-device-enrollment), being federated means that the MDM + endpoints and details were fetched from a Discovery endpoint, + instead of being manually installed. The page does not make mention + of the specific registry key, but we are making an assumption that + it means the same thing. + - `ProviderID` + Set during enrollment. In our case it's the word "Fleet". + - `RenewalPeriod` + Set during enrollment. Period to renew WSTEP certificate. + - `RenewErrorCode` + Presumably set if there is an error renewing WSTEP certificate. + - `RenewROBOSupport` + According to [this post](https://call4cloud.nl/2022/10/fullmetal-certificate-the-revenge-of-renewal/) this means "Request On Behalf Of". + It seems to have to do with automatic certificate renewal + - `RenewStatus` + Status of the renewal + - `RenewTimestamp` + Presumably the timestamp of the last renewal + - `RootCertThumbPrint` + The thumbprint of the WSTEP root certificate + - `SID` + Security Identifier + - `UPN` + User Principal Name of the user that enrolled the device + - `AADResourceID` + Appears to be the domain of the server managing the enrollment, + always appears to be present on machines enrolled through Microsoft + Entra (Azure Active Directory) + - `AADTenantID` + Also related to Azure Active Directory, and also appears to be + present at the same time as AADResourceID. +- `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Provisioning\Diagnostics\AutoPilot` + Autopilot provisioning diagnostic data + + + diff --git a/docs/Deploy/Deploy-Fleet-on-AWS-ECS.md b/docs/Deploy/Deploy-Fleet-on-AWS-ECS.md new file mode 100644 index 000000000..a1601178e --- /dev/null +++ b/docs/Deploy/Deploy-Fleet-on-AWS-ECS.md @@ -0,0 +1,28 @@ +## Deploy Fleet on AWS ECS + +Terraform reference architecture can be found [here](https://github.com/fleetdm/fleet/tree/main/infrastructure/dogfood/terraform/aws) + +### Infrastructure dependencies + +#### MySQL + +In AWS we recommend running Aurora with MySQL Engine, see [here for terraform details](https://github.com/fleetdm/fleet/blob/main/infrastructure/dogfood/terraform/aws/rds.tf#L64). + +#### Redis + +In AWS we recommend running ElastiCache (Redis Engine) see [here for terraform details](https://github.com/fleetdm/fleet/blob/main/infrastructure/dogfood/terraform/aws/redis.tf#L13) + +#### Fleet server + +Running Fleet in ECS consists of two main components the [ECS Service](https://github.com/fleetdm/fleet/blob/main/infrastructure/dogfood/terraform/aws/ecs.tf#L84) & [Load Balancer](https://github.com/fleetdm/fleet/blob/main/infrastructure/dogfood/terraform/aws/ecs.tf#L59). In our example the ALB is [handling TLS termination](https://github.com/fleetdm/fleet/blob/main/infrastructure/dogfood/terraform/aws/ecs.tf#L46) + +#### Fleet migrations + +Migrations in ECS can be achieved by running [dedicated ECS tasks](https://github.com/fleetdm/fleet/tree/main/infrastructure/dogfood/terraform/aws#migrating-the-db) that run the `fleet prepare --no-prompt=true db` command. See [terraform for more details](https://github.com/fleetdm/fleet/blob/main/infrastructure/dogfood/terraform/aws/ecs.tf#L261) + +Alternatively you can bake the prepare command into the same task definition see [here for a discussion](https://github.com/fleetdm/fleet/pull/1761#discussion_r697599457), but this is not recommended for production environments. + + + + + \ No newline at end of file diff --git a/docs/Deploy/Deploy-Fleet-on-CentOS.md b/docs/Deploy/Deploy-Fleet-on-CentOS.md new file mode 100644 index 000000000..016a3c94b --- /dev/null +++ b/docs/Deploy/Deploy-Fleet-on-CentOS.md @@ -0,0 +1,220 @@ +## Deploy Fleet on CentOS + +In this guide, we're going to install Fleet and all of its application dependencies on a CentOS 7.1 server. Once we have Fleet up and running, we're going to install osquery on that same CentOS 7.1 host and enroll it in Fleet. This should give you a good understanding of both how to install Fleet as well as how to install and configure osquery such that it can communicate with Fleet. + +### Setting up a host + +If you don't have a CentOS host readily available, Fleet recommends using [Vagrant](https://www.vagrantup.com/) for this guide. You can find installation instructions on Vagrant's [downloads page](https://developer.hashicorp.com/vagrant/downloads). + +Once you have installed Vagrant, run the following to create a Vagrant box, start it, and log into it: + +```sh +echo 'Vagrant.configure("2") do |config| + config.vm.box = "bento/centos-7.1" + config.vm.network "forwarded_port", guest: 8080, host: 8080 +end' > Vagrantfile +vagrant up +vagrant ssh +``` + +### Installing Fleet + +To install Fleet, [download](https://github.com/fleetdm/fleet/releases) the latest release from GitHub. The binary is in an archive that uses this naming convention, including the current version: `fleet_
+
+
+
+## Create a query
+
+Queries in Fleet allow you to ask a multitude of questions to help you manage, monitor, and identify threats on your devices.
+
+If you're unsure of what to ask, head to Fleet's [query library](https://fleetdm.com/queries). There you'll find common queries that have been tested by members of our community.
+
+How to create a query:
+
+1. In the top navigation, select **Queries**.
+
+2. Select **Create new query** to navigate to the query console.
+
+3. In the **Query** field, enter your query. Remember, you can find common queries in [Fleet's library](https://fleetdm.com/queries).
+
+4. Select **Save**, enter a name and description for your query, select the frequency that the query should run at, and select **Save query**.
+
+## Run a query
+
+Run a live query to get answers for all of your online hosts.
+
+> Offline hosts won’t respond to a live query because they may be shut down, asleep, or not connected to the internet.
+
+How to run a query:
+
+1. In the top navigation, select **Queries**.
+
+2. In the **Queries** table, find the query you'd like to run and select the query's name to navigate to the query console.
+
+3. Select **Run query** to navigate to the target picker. Select **All hosts** and select **Run**. This will run the query against all your hosts.
+
+The query may take several seconds to complete because Fleet has to wait for the hosts to respond with results.
+
+> Fleet's query response time is inherently variable because of osquery's heartbeat response time. This helps prevent performance issues on hosts.
+
+## Schedule a query
+
+*In Fleet 4.35.0, the "Schedule" page was removed, and query automations are now configured on the "Queries" page. Instructions for scheduling queries in earlier versions of Fleet can be found [here](https://github.com/fleetdm/fleet/blob/ac797c8f81ede770853c25fd04102da9f5e109bf/docs/Using-Fleet/Fleet-UI.md#schedule-a-query).*
+
+Fleet allows you to schedule queries to run at a set frequency. Scheduled queries will send data to Fleet and/or your [log destination](https://fleetdm.com/docs/using-fleet/log-destinations) automatically.
+
+By default, queries that run on a schedule will only target platforms compatible with that query. This behavior can be overridden by setting the platforms in **Advanced options** when saving a query.
+
+**How to send data to your log destination:**
+
+*Only users with the [admin role](https://fleetdm.com/docs/using-fleet/manage-access#admin) can manage query automations.*
+
+1. In the top navigation, select **Queries**.
+
+2. Select **Manage automations**.
+
+3. Check the box next to the queries you want to send data to your log destination, and select **Save**. (The frequency that queries run at is set when a query is created.)
+
+> Note: When viewing a specific [team](https://fleetdm.com/docs/using-fleet/segment-hosts) in Fleet Premium, only queries that belong to the selected team will be listed. When configuring query automations for all hosts, only global queries will be listed.
+
+## Update agent options
+
+
+
+
+> This content was relocated on 31st August 2023.
+
+See "[Agent configuration](https://fleetdm.com/docs/configuration/agent-configuration)" to learn how to simultaneously update agent options from the Fleet UI or fleetctl command line tool.
+
+
+
+
+
diff --git a/docs/Using-Fleet/Fleet-desktop.md b/docs/Using Fleet/Fleet-desktop.md
similarity index 89%
rename from docs/Using-Fleet/Fleet-desktop.md
rename to docs/Using Fleet/Fleet-desktop.md
index a2c1efa71..33846fb9d 100644
--- a/docs/Using-Fleet/Fleet-desktop.md
+++ b/docs/Using Fleet/Fleet-desktop.md
@@ -20,7 +20,7 @@ At its core, Fleet Desktop gives your end users visibility into the security pos
For information on how to install Fleet Desktop, visit: [Adding Hosts](https://fleetdm.com/docs/using-fleet/adding-hosts#fleet-desktop).
## Upgrading Fleet Desktop
-Once installed, Fleet Desktop will be automatically updated via Orbit. To learn more, visit: [Self-managed agent updates](https://fleetdm.com/docs/deploying/fleetctl-agent-updates#self-managed-agent-updates).
+Once installed, Fleet Desktop will be automatically updated via Fleetd. To learn more, visit: [Self-managed agent updates](https://fleetdm.com/docs/deploying/fleetctl-agent-updates#self-managed-agent-updates).
## Custom transparency link
For organizations with complex security postures, they can direct end users to a resource of their choice to serve custom content.
@@ -30,7 +30,7 @@ For organizations with complex security postures, they can direct end users to a
To turn on the custom transparency link in the Fleet GUI, click on your profile in the top right and select "Settings."
On the settings page, go to "Organization Settings" and select "Fleet Desktop." Use the "Custom transparency URL" text input to specify the custom URL.
-For information on how to set the custom transparency link via a YAML configuration file, see the [configuration files](https://fleetdm.com/docs/deploying/configuration#fleet-desktop-settings) documentation.
+For information on how to set the custom transparency link via a YAML configuration file, see the [configuration files](https://fleetdm.com/docs/configuration/fleet-server-configuration#fleet-desktop-settings) documentation.
## Securing Fleet Desktop
@@ -59,3 +59,5 @@ This change is imperceptible to users, as clicking on the "My Device" tray item
+
+
diff --git a/docs/Using-Fleet/Learn-how-to-use-Fleet.md b/docs/Using Fleet/Learn-how-to-use-Fleet.md
similarity index 92%
rename from docs/Using-Fleet/Learn-how-to-use-Fleet.md
rename to docs/Using Fleet/Learn-how-to-use-Fleet.md
index b258d8c26..c9dfb7442 100644
--- a/docs/Using-Fleet/Learn-how-to-use-Fleet.md
+++ b/docs/Using Fleet/Learn-how-to-use-Fleet.md
@@ -54,3 +54,5 @@ When the query has finished, you should see several columns in the "Results" tab
- The "version" column answers: "What version of the installed operating system is on my device?"
+
+
\ No newline at end of file
diff --git a/docs/Using-Fleet/Log-destinations.md b/docs/Using Fleet/Log-destinations.md
similarity index 96%
rename from docs/Using-Fleet/Log-destinations.md
rename to docs/Using Fleet/Log-destinations.md
index b11c752a1..fb153f258 100644
--- a/docs/Using-Fleet/Log-destinations.md
+++ b/docs/Using Fleet/Log-destinations.md
@@ -16,8 +16,11 @@ This document provides a list of the supported log destinations in Fleet.
Log destinations can be used in Fleet to log:
- Osquery [status logs](https://osquery.readthedocs.io/en/stable/deployment/logging/#status-logs).
+
- Osquery [schedule query result logs](https://osquery.readthedocs.io/en/stable/deployment/logging/#results-logs).
-- Fleet audit logs.
+
+- Fleet [audit logs](https://fleetdm.com/docs/using-fleet/audit-logs).
+
To configure each log destination, you must set the correct logging configuration options in Fleet.
Check out the reference documentation for:
@@ -142,4 +145,6 @@ See the [osquery logging documentation](https://osquery.readthedocs.io/en/stable
If `--logger_plugin=tls` is used with osquery clients, the following configuration can be applied on the Fleet server for handling the incoming logs.
-
\ No newline at end of file
+
+
+
diff --git a/docs/Using Fleet/MDM-OS-updates.md b/docs/Using Fleet/MDM-OS-updates.md
new file mode 100644
index 000000000..c10adb06a
--- /dev/null
+++ b/docs/Using Fleet/MDM-OS-updates.md
@@ -0,0 +1,50 @@
+# OS updates
+
+_Available in Fleet Premium_
+
+In Fleet you can enforce OS updates on your macOS and Windows hosts remotely.
+
+## Enforce OS updates
+
+You can enforce OS updates using the Fleet UI, Fleet API, or [Fleet's GitOps workflow](https://github.com/fleetdm/fleet-gitops).
+
+Fleet UI:
+
+1. Head to the **Controls** > **OS updates** tab.
+
+2. To enforce OS updates for macOS, select **macOS** and set a **Minimum version** and **Deadline**.
+
+3. For Windows, select **Windows** and set a **Deadline** and **Grace period**.
+
+Fleet API: API documentation is [here](https://fleetdm.com/docs/rest-api/rest-api#modify-team).
+
+## End user experience
+
+### macOS
+
+End users are encouraged to update macOS (via [Nudge](https://github.com/macadmins/nudge)).
+
+
+
+| | > 1 day before deadline | < 1 day before deadline | Past deadline |
+| ------------------------------------ | ----------------------- | ----------------------- | --------------------- |
+| Nudge window frequency | Once a day at 8pm GMT | Once every 2 hours | Immediately on login |
+| End user can defer | ✅ | ✅ | ❌ |
+| Nudge window is dismissible | ✅ | ✅ | ❌ |
+
+### Windows
+
+End users are encouraged to update Windows via the native Windows dialog.
+
+| | Before deadline | Past deadline |
+| ----------------------------------------- | ----------------| ------------- |
+| End user can defer automatic restart | ✅ | ❌ |
+
+If an end user was on vacation when the deadline passed, the end user is given a grace period (configured) before the host automatically restarts.
+
+Fleet enforces OS updates for quality and feature updates. Read more about the types of Windows OS updates in the Microsoft documentation [here](https://learn.microsoft.com/en-us/windows/deployment/update/get-started-updates-channels-tools#types-of-updates).
+
+
+
+
+
diff --git a/docs/Using Fleet/MDM-commands.md b/docs/Using Fleet/MDM-commands.md
new file mode 100644
index 000000000..229ba15d1
--- /dev/null
+++ b/docs/Using Fleet/MDM-commands.md
@@ -0,0 +1,101 @@
+# Commands
+
+In Fleet you can run MDM commands to take action on your macOS and Windows hosts, like restarting the host, remotely.
+
+## Custom commands
+
+You can run custom commands and view a specific command's results using the `fleetctl` command-line interface.
+
+To run a custom command, we will do the following steps:
+
+1. Create a `.xml` with the request payload
+2. Choose a target host
+3. Run the command using `fleetctl`
+4. View our command's results using `fleetctl`
+
+### Step 1: Create an XML file
+
+You can run any command supported by [Apple's MDM protocol](https://developer.apple.com/documentation/devicemanagement/commands_and_queries) or [Microsoft's MDM protocol](https://learn.microsoft.com/en-us/windows/client-management/mdm/).
+
+> The lock and wipe commands are only available in Fleet Premium
+
+For example, to restart a macOS host, we'll use the "Restart a Device" command documented by Apple [here](https://developer.apple.com/documentation/devicemanagement/restart_a_device#3384428).
+
+First, we'll need to create a `restart-device.xml` file locally with this payload:
+
+```xml
+
+
+
+
+## Migrate automatically enrolled (DEP) hosts
+
+> Automatic enrollment is available in Fleet Premium or Ultimate
+
+To migrate automatically enrolled hosts, we will do the following steps:
+
+1. Prepare to migrate hosts
+2. Choose migration workflow and migrate hosts
+
+### Step 1: prepare to migrate hosts
+
+1. Connect Fleet to Apple Business Manager (ABM). Learn how [here](./mdm-macos-setup.md#apple-business-manager-abm).
+2. [Enroll](./Adding-hosts.md) your hosts to Fleet with [Fleetd and Fleet Desktop](https://fleetdm.com/docs/using-fleet/adding-hosts#including-fleet-desktop)
+3. Ensure your end users have access to an admin account on their Mac. End users won't be able to migrate on their own if they have a standard account.
+4. Migrate your hosts to Fleet in ABM:
+ 1. In ABM, unassign the existing hosts' MDM server from the old MDM solution: In ABM, select **Devices** and then select **All Devices**. Then, select **Edit** next to **Edit MDM Server**, select **Unassign from the current MDM**, and select **Continue**.
+ 2. In ABM, assign these hosts' MDM server to Fleet: In ABM, select **Devices** and then select **All Devices**. Then, select **Edit** next to **Edit MDM Server**, select **Assign to the following MDM:**, select your Fleet server in the dropdown, and select **Continue**.
+
+### Step 2: choose migration workflow and migrate hosts
+
+There are two migration workflows in Fleet: default and end user.
+
+The default migration workflow requires that the IT admin unenrolls hosts from the old MDM solution before the end user can complete migration. This will result in a gap in MDM coverage until the end user completes migration.
+
+The end user migration workflow allows the end user to kick-off migration by unenrolling from the old MDM solution on their own. Once the user is unenrolled, they're prompted to turn on MDM features in Fleet. This reduces the gap in MDM coverage.
+
+Configuring the end user migration workflow requires a few additional steps.
+
+#### Default workflow
+
+1. In your old MDM solution, unenroll the hosts to be migrated. MacOS does not allow multiple MDMs to be installed at once.
+
+2. Send [these guided instructions](#how-to-turn-on-mdm-default) to your end users to complete the final few steps via Fleet Desktop.
+ * Note that there will be a gap in MDM coverage between when the host is unenrolled from the old MDM and when the host turns on MDM in Fleet.
+
+##### End user experience
+
+1. The end user will receive a "Device Enrollment: <organization> can automatically configure your Mac." system notification within the macOS Notifications Center.
+
+2. After the end user clicks on the system notification, macOS will open the **System Setting > Profiles** and ask the user to "Allow Device Enrollment: <organization> can automatically configure your Mac based on settings provided by your System Administrator."
+
+3. If the end user does not install the profile, the system notification will continue to prompt the end user until the setting has been allowed.
+
+4. Once this setting has been approved, the MDM enrollment profile cannot be removed by the end user.
+
+##### How to turn on MDM (default)
+
+1. Select the Fleet icon in your menu bar and select **My device**.
+
+
+
+2. On your **My device** page, select the **Turn on MDM** button in the yellow banner and follow the instructions.
+ * If you don’t see the yellow banner or the **Turn on MDM** button, select the purple **Refetch** button at the top of the page.
+ * If you still don't see the **Turn on MDM** button or the **My device** page presents you with an error, please contact your IT administrator.
+
+
+
+#### End user workflow
+
+> Available in Fleet Premium or Ultimate
+
+The end user migration workflow is supported for automatically enrolled (DEP) hosts.
+
+To watch a GIF that walks through the end user experience during the migration workflow, in the Fleet UI, head to **Settings > Integrations > Mobile device management (MDM)**, and scroll down to the **End user migration workflow** section.
+
+In Fleet, you can configure the end user workflow using the Fleet UI or fleetctl command-line tool.
+
+Fleet UI:
+
+1. Select the avatar on the right side of the top navigation and select **Settings > Integrations > Mobile device management (MDM)**.
+
+2. Scroll down to the **End user migration workflow** section and select the toggle to enable the workflow.
+
+3. Under **Mode** choose a mode and enter the webhook URL for you automation tool (ex. Tines) under **Webhook URL** and select **Save**.
+
+4. During the end user migration workflow, an end user's device will have their selected system theme (light or dark) applied. If your logo is not easy to see on both light and dark backgrounds, you can optionally set a logo for each theme:
+Head to **Settings** > **Organization settings** >
+**Organization info**, add URLs to your logos in the **Organization avatar URL (for dark backgrounds)** and **Organization avatar URL (for light backgrounds)** fields, and select **Save**.
+
+fleetctl CLI:
+
+1. Create `fleet-config.yaml` file or add to your existing `config` YAML file:
+
+```yaml
+apiVersion: v1
+kind: config
+spec:
+ mdm:
+ macos_migration:
+ enable: true
+ mode: "voluntary"
+ webhook_url: "https://example.com"
+ ...
+```
+
+2. Fill in the above keys under the `mdm.macos_migration` key.
+
+To learn about each option, in the Fleet UI, select the avatar on the right side of the top navigation, select **Settings > Integrations > Mobile device management (MDM)**, and scroll down to the **End user migration workflow** section.
+
+3. During the end user migration workflow, the window will show the Fleet logo on top of a dark and light background (appearance configured by end user).
+
+If want to add a your organization's logo, you can optionally set a logo for each background:
+
+```yaml
+apiVersion: v1
+kind: config
+spec:
+ org_info:
+ org_logo_url: https://fleetdm.com/images/press-kit/fleet-blue-logo.png
+ org_logo_url_light_background: https://fleetdm.com/images/press-kit/fleet-white-logo.png
+ ...
+```
+
+Add URLs to your logos that are visible on a dark background and light background in the `org_logo_url` and `org_logo_url_light_background` keys respectively. If you only set a logo for one, the Fleet logo will be used for the other.
+
+4. Run the fleetctl `apply -f fleet-config.yml` command to add your configuration.
+
+5. Confirm that your configuration was saved by running `fleetctl get config`.
+
+6. Send [these guided instructions](#how-to-turn-on-mdm-end-user) to your end users to complete the final few steps via Fleet Desktop.
+
+##### How to turn on MDM (end user)
+
+1. Select the Fleet icon in your menu bar and select **Migrate to Fleet**.
+
+2. Select **Start** in the **Migrate to Fleet** popup.
+
+2. On your **My device** page, select the **Turn on MDM** button in the yellow banner and follow the instructions.
+ * If you don’t see the yellow banner or the **Turn on MDM** button, select the purple **Refetch** button at the top of the page.
+ * If you still don't see the **Turn on MDM** button or the **My device** page presents you with an error, please contact your IT administrator.
+
+## Check migration progress
+
+To see a report of which hosts have successfully migrated to Fleet, have MDM features off, or are still enrolled to your old MDM solution head to the **Dashboard** page by clicking the icon on the left side of the top navigation bar.
+
+Then, scroll down to the **Mobile device management (MDM)** section.
+
+## FileVault recovery keys
+
+_Available in Fleet Premium_
+
+When migrating from a previous MDM, end users need to take action to escrow FileVault keys to Fleet. The **My device** page in Fleet Desktop will present users with instructions to reset their key.
+
+To start, enforce FileVault (disk encryption) and escrow in Fleet. Learn how [here](./MDM-disk-encryption.md).
+
+After turning on disk encryption in Fleet, share [these guided instructions](#how-to-turn-on-disk-encryption) with your end users.
+
+If your old MDM solution did not enforce disk encryption, the end user will need to restart or log out of the host.
+
+If your old MDM solution did enforce disk encryption, the end user will need to reset their disk encryption key by following the prompt on the My device page and inputting their password.
+
+## Activation Lock Bypass codes
+
+In Fleet, the [Activation Lock](https://support.apple.com/en-us/HT208987) feature is disabled by default for automatically enrolled (DEP) hosts.
+
+If a host under the old MDM solution has Activation Lock enabled, we recommend asking the end user to follow these instructions to disable Activation Lock before migrating this host to Fleet: https://support.apple.com/en-us/HT208987.
+
+This is because if the Activation Lock is enabled, you will need the Activation Lock bypass code to successfully wipe and reuse the Mac.
+
+However, Activation Lock bypass codes can only be retrieved from the Mac up to 30 days after the device is enrolled. This means that when migrating from your old MDM solution, it’s likely that you’ll be unable to retrieve the Activation Lock bypass code.
+
+### How to turn on disk encryption
+
+1. Select the Fleet icon in your menu bar and select **My device**.
+
+
+
+2. On your **My device** page, follow the disk encryption instructions in the yellow banner.
+ - If you don’t see the yellow banner, select the purple **Refetch** button at the top of the page.
+ - If you still don't see the yellow banner after a couple minutes or if the **My device** page presents you with an error, please contact your IT administrator.
+
+
+
+
+
+
+
diff --git a/docs/Using-Fleet/Osquery-process.md b/docs/Using Fleet/Osquery-process.md
similarity index 92%
rename from docs/Using-Fleet/Osquery-process.md
rename to docs/Using Fleet/Osquery-process.md
index 2f1cfeba5..68efcd81d 100644
--- a/docs/Using-Fleet/Osquery-process.md
+++ b/docs/Using Fleet/Osquery-process.md
@@ -25,4 +25,6 @@ If the managed extension is `Non-existent` (either because it was `Non-existent`
Lastly, we check the state of the watcher process itself. If it is deemed unhealthy because of resource contention, then the osquery process is shut down.
-
\ No newline at end of file
+
+
+
\ No newline at end of file
diff --git a/docs/Using Fleet/Puppet-module.md b/docs/Using Fleet/Puppet-module.md
new file mode 100644
index 000000000..8aa09d03a
--- /dev/null
+++ b/docs/Using Fleet/Puppet-module.md
@@ -0,0 +1,157 @@
+# Puppet module
+
+_Available in Fleet Premium_
+
+Use [Fleet's Puppet module](https://forge.puppet.com/modules/fleetdm/fleetdm/readme) to automatically install custom configuration profiles on your macOS hosts based on host attributes you define in Puppet.
+
+The module also includes functions for releasing a macOS host from [Await Configuration](https://developer.apple.com/documentation/devicemanagement/release_device_from_await_configuration) and sending any custom MDM commands.
+
+## Setup
+
+To set up the Puppet module, we will do the following steps:
+
+1. Install the Puppet module
+2. Configure Puppet to talk to Fleet using Hiera
+3. Set Fleet as a reporter
+
+### Step 1: install the Puppet module
+
+Install [Fleet's Puppet module](https://forge.puppet.com/modules/fleetdm/fleetdm/readme). For more instructions on how to install Puppet modules, check out the Puppet docs [here](https://www.puppet.com/docs/puppet/8/modules_installing.html).
+
+### Step 2: configure Puppet to talk to Fleet using Heira
+
+1. In Fleet, create an API-only user with the global admin role. Instructions for creating an API-only user are [here](./fleetctl-CLI.md#create-an-api-only-user).
+
+2. Get the API token for your new API-only user. Learn how [here](./fleetctl-CLI.md#get-the-api-token-of-an-api-only-user).
+
+3. Set `fleetdm::host` and `fleetdm::token` values to your Fleet server's URL and the API token respectively. Here's an example of the Hiera YAML:
+
+```yaml
+fleetdm::host: https://fleet.example.com
+fleetdm::token: your-api-token
+```
+
+Puppet docs on configuring Hiera are [here](https://www.puppet.com/docs/puppet/6/hiera_config_yaml_5.html).
+
+If you have staging and production Puppet environments, you can optionally set different values for each environment. This allows you to have your staging and production environments that talk to separate staging and production Fleet servers.
+
+### Step 3: set Fleet as a reporter
+
+In your Puppet configuration, set `http:fleetdm` as the value for `reports`. Here's an example of the Puppet configuration:
+
+```
+reports = http,fleetdm
+```
+
+Puppet configuration reference docs are [here](https://www.puppet.com/docs/puppet/7/configuration#reports).
+
+## Install configuration profiles
+
+Using the Puppet module you can define the set of configuration profiles for each host (Puppet node) and Fleet will create a team with these profiles and assign the host to that team.
+
+When a host is assigned to a team in Fleet, all configuration profiles for that team are installed on the host.
+
+As an example, let's install one configuration profile on all hosts. Here's what your Puppet code will look like:
+
+```pp
+node default {
+ fleetdm::profile { 'com.apple.payload.identifier':
+ template => template('example-profile.mobileconfig'),
+ group => 'MacOS workstations',
+ }
+}
+```
+
+This will create a team called "MacOS workstations" with the `example-profile.mobileconfig` configuration profile and assign all hosts to this team.
+
+Use the `group` parameter to define the team name in Fleet.
+
+As another example, let's assign one configuration profile to all hosts and another configuration profile to only my M1 hosts. Here's what your Puppet code will look like:
+
+```pp
+node default {
+ fleetdm::profile { 'com.apple.payload.identifier-1':
+ template => template('example-profile.mobileconfig'),
+ group => 'MacOS workstations',
+ }
+
+ if $facts['architecture'] == 'intel' {
+ fleetdm::profile { 'com.apple.payload.identifier-2':
+ ensure => absent,
+ template => template('m1-only.mobileconfig'),
+ group => 'Intel',
+ }
+ } else {
+ fleetdm::profile { 'com.apple.example-2':
+ template => template('com.apple.payload.identifier-2'),
+ group => 'MacOS workstations',
+ }
+ }
+}
+```
+
+This will create two teams in Fleet:
+
+1. "MacOS workstations" with two configuration profiles: `example-profile.mobileconfig` and `m1-only.mobileconfig`.
+2. "MacOS workstations - Intel" with one configuration profile: `example-profile.mobileconfig`.
+
+Set the `ensure` parameter to `absent` to create teams that exclude specific profiles.
+
+For more examples check out the `examples/` folder in Fleet's GitHub repository [here](https://github.com/fleetdm/fleet/tree/main/ee/tools/puppet/fleetdm/examples).
+
+> Note that all teams created by Puppet inherit the bootstrap package, macOS Setup Assistant settings, and end user authentication settings from "No team." Learn more about these [here](./MDM-macOS-setup.md). In addition all teams automatically enable disk encryption. Learn more about disk encryption [here](./MDM-disk-encryption.md).
+
+## Release host
+
+If you set `await_device_configured` to `true` in your [macOS Setup Assistant settings](./MDM-macOS-setup.md#macos-setup-assistant), you can use the `fleetdm::release_device` function to release the host from the Setup Assistant.
+
+Here's what your Puppet code, with error handling, will look like:
+
+```pp
+$host_uuid = $facts['system_profiler']['hardware_uuid']
+$response = fleetdm::release_device($host_uuid)
+$err = $response['error']
+
+if $err != '' {
+ notify { "error releasing device: ${err}": }
+}
+```
+
+## Custom commands
+
+You can use the `fleetdm::command_xml` function to send any custom MDM command to a host.
+
+Here's what your Puppet code, with error handling, will look like:
+
+```pp
+$host_uuid = $facts['system_profiler']['hardware_uuid']
+$command_uuid = generate('/usr/bin/uuidgen').strip
+
+$xml_data = "
+
+
+
+
+
+## Coverage
+
+Fleet detects vulnerabilities for these software types:
+
+| Type | macOS | Windows | Linux |
+| ------------------- | ------------------------------------------ | ------------------------------------------------ | ---------------- |
+| Apps | ✅ | ✅ | ❌ |
+| Browser plugins | Chrome extensions, Firefox extensions | Chrome extensions, Firefox extensions | ❌ |
+| Packages | Python, Homebrew | Python, Atom, Chocolatey | Adhere to whatever is defined in the [OVAL definitions](https://github.com/fleetdm/nvd/blob/master/oval_sources.json), except for kernel vulnerabilities and vulnerabilities involving configuration files. Supported distributions: - Ubuntu
- RHEL based distros (Red Hat, CentOS, Fedora, and Amazon Linux)
(default: tuf.fleetctl.com)"]; + fleet_server[Fleet
Server]; + subgraph fleetd + orbit[orbit]; + desktop[Fleet Desktop
Tray App]; + osqueryd[osqueryd]; + desktop_browser[Fleet Desktop
from Browser]; + end + orbit -- "Fleet Orbit API (TLS)" --> fleet_server; + desktop -- "Fleet Desktop API (TLS)" --> fleet_server; + osqueryd -- "osquery
remote API (TLS)" --> fleet_server; + desktop_browser -- "My Device API (TLS)" --> fleet_server; + orbit -- "Auto Update (TLS)" --> tuf; +``` + +### Signing fleetd installers + + >**Note:** Currently, the `fleetctl package` command does not support signing Windows fleetd installers. Windows installers can be signed after building. + +The `fleetctl package` command supports signing and notarizing macOS osquery installers via the +`--sign-identity` and `--notarize` flags. + +Check out the example below: + +```sh + AC_USERNAME=appleid@example.com AC_PASSWORD=app-specific-password fleetctl package --type pkg --sign-identity=[PATH TO SIGN IDENTITY] --notarize --fleet-url=[YOUR FLEET URL] --enroll-secret=[YOUR ENROLLMENT SECRET] +``` + +The above command must be run on a macOS device, as the notarizing and signing of macOS fleetd installers can only be done on macOS devices. + +Also, remember to replace both `AC_USERNAME` and `AC_PASSWORD` environment variables with your Apple ID and a valid [app-specific](https://support.apple.com/en-ca/HT204397) password, respectively. Some organizations (notably those with Apple Enterprise Developer Accounts) may also need to specify `AC_TEAM_ID`. This value can be found on the [Apple Developer "Membership" page](https://developer.apple.com/account/#!/membership) under "Team ID." + +### Grant full disk access to osquery on macOS + +MacOS does not allow applications to access all system files by default. + +If you are using an MDM solution or Fleet's MDM features, one of which is required to deploy these profiles, you can deploy a "Privacy Preferences Policy Control" policy to grant fleetd or osquery that level of access. + +This is required to query for files located in protected paths as well as to use event +tables that require access to the [EndpointSecurity API](https://developer.apple.com/documentation/endpointsecurity#overview), such as *es_process_events*. + +#### Creating the configuration profile + +##### Obtaining identifiers + +If you use plain osquery, instructions are [available here](https://osquery.readthedocs.io/en/stable/deployment/process-auditing/). + +On a system with osquery installed via the Fleet osquery installer (fleetd), obtain the +`CodeRequirement` of fleetd by running: + +```sh +codesign -dr - /opt/orbit/bin/orbit/macos/stable/orbit +``` + +The output should be similar or identical to: + +```sh +Executable=/opt/orbit/bin/orbit/macos/edge/orbit +designated => identifier "com.fleetdm.orbit" and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = "8VBZ3948LU" +``` + +Note down the **executable path** and the entire **identifier**. + +Osqueryd will inherit the privileges from Orbit and does not need explicit permissions. + +##### Creating the profile + +Depending on your MDM, this might be possible in the UI or require a custom profile. If your MDM has a feature to configure *Policy Preferences*, follow these steps: + +1. Configure the identifier type to “path.” +2. Paste the full path to Orbit as the identifier. +3. Paste the full code signing identifier into the Code requirement field. +4. Allow “Access all files.” Access to Downloads, Documents, etc., is inherited from this. + +If your MDM solution does not have built-in support for privacy preferences profiles, you can use +[PPPC-Utility](https://github.com/jamf/PPPC-Utility) to create a profile with those values, then upload it to +your MDM as a custom profile. + +##### Test the profile +Link the profile to a test group that contains at least one Mac. +Once the computer has received the profile, which you can verify by looking at *Profiles* in *System +Preferences*, run this query from Fleet: + +```sql +SELECT * FROM file WHERE path LIKE '/Users/%/Downloads/%%'; +``` + +If this query returns files, the profile was applied, as **Downloads** is a +protected location. You can now enjoy the benefits of osquery on all system files and start +using the **es_process_events** table! + +If this query does not return data, you can look at operating system logs to confirm whether or not full disk +access has been applied. + +See the last hour of logs related to TCC permissions with this command: + +`log show --predicate 'subsystem == "com.apple.TCC"' --info --last 1h` + +You can then look for `orbit` or `osquery` to narrow down results. + +### Using mTLS + +`Applies only to Fleet Premium` + +Fleetd supports using TLS client certificates for authentication to the Fleet server and [TUF](https://theupdateframework.io/) server. + +When generating the packages, use the following flags: +```sh +fleetctl package \ + [...] + --fleet-tls-client-certificate=fleet-client.crt \ + --fleet-tls-client-key=fleet-client.key \ + --update-tls-client-certificate=update-client.crt \ + --update-tls-client-key=update-client.key \ + [...] +``` +The certificates must be in PEM format. + +The client certificates can also be pushed to existing installations by placing them in the following locations: +- For macOS and Linux: + - `/opt/orbit/fleet_client.crt` + - `/opt/orbit/fleet_client.key` + - `/opt/orbit/update_client.crt` + - `/opt/orbit/update_client.key` +- For Windows: + - `C:\Program Files\Orbit\fleet_client.crt` + - `C:\Program Files\Orbit\fleet_client.key` + - `C:\Program Files\Orbit\update_client.crt` + - `C:\Program Files\Orbit\update_client.key` + +If using Fleet Desktop, you may need to specify an alternative host for the "My device" URL (in the Fleet tray icon). +Such alternative host should not require client certificates on the TLS connection. +```sh +fleetctl package + [...] + --fleet-desktop \ + --fleet-desktop-alternative-browser-host=fleet-desktop.example.com \ + [...] +``` +If this setting is not used, you will need to configure client TLS certificates on devices' browsers. + +### Specifying update channels + +Fleetd uses the concept of "update channels" to determine the version of it's components: Orbit, Fleet Desktop, osquery. + +Configure update channels for these components with the `--orbit-channel`, `--desktop-channel` and `--osqueryd-channel` flags when running the `fleetctl package command`. + +| Channel | Versions | +| ------- | -------- | +| `4` | 4.x.x | +| `4.6` | 4.6.x | +| `4.6.0` | 4.6.0 | + +Additionally, `stable` and `edge` are special channel names. The `stable` channel will provide the most recent osquery version that Fleet deems to be stable. + +When a new version of osquery is released, it's added to the `edge` channel for beta testing. Fleet then provides input to the osquery TSC based on testing. After the version is declared stable by the osquery TSC, Fleet will promote the version to `stable` ASAP. + +### Testing osquery queries locally + +Fleet comes packaged with `osqueryi` which is a tool for testing osquery queries locally. + +With fleetd installed on your host, run `orbit osqueryi` or `orbit shell` to open the `osqueryi`. + +### Finding fleetd logs + +Fleetd will send stdout/stderr logs to the following directories: + + - macOS: `/private/var/log/orbit/orbit.std{out|err}.log`. + - Windows: `C:\Windows\system32\config\systemprofile\AppData\Local\FleetDM\Orbit\Logs\orbit-osquery.log` (the log file is rotated). + - Linux: Orbit and osqueryd stdout/stderr output is sent to syslog (`/var/log/syslog` on Debian systems and `/var/log/messages` on CentOS). + +If the `logger_path` agent configuration is set to `filesystem`, fleetd will send osquery's "result" and "status" logs to the following directories: + - Windows: C:\Program Files\Orbit\osquery_log + - macOS: /opt/orbit/osquery_log + - Linux: /opt/orbit/osquery_log + +### Using system keystore for enroll secret + +On macOS and Windows, fleetd will add the enroll secret to the system keystore (Keychain on macOS, Credential Manager on Windows) on launch. Subsequent launches will retrieve the enroll secret from the keystore. + +System keystore access can be disabled via `--disable-keystore` flag for the `fleetctl package` command. On macOS, subsequent installations of fleetd must be signed by the same organization as the original installation to access the enroll secret in the keychain. + +>**Note:** The keychain is not used on macOS when the enroll secret is provided via MDM profile. Keychain support when passing the enroll secret via MDM profile is coming soon. + +### Generating Windows installers using local WiX toolset + +`Applies only to Fleet Premium` + +When creating a fleetd installer for Windows hosts (**.msi**) on a Windows or macOS machine, you can tell `fleetctl package` to +use local installations of the 3 WiX v3 binaries used by this command (`heat.exe`, `candle.exe`, and +`light.exe`) instead of those in a pre-configured container, which is the default behavior. To do +so: + 1. Install the WiX v3 binaries. To install, you can download them + [here](https://github.com/wixtoolset/wix3/releases/download/wix3112rtm/wix311-binaries.zip), then unzip the downloaded file. + 2. Find the absolute filepath of the directory containing your local WiX v3 binaries. This will be wherever you saved the unzipped package contents. + 3. Run `fleetctl package`, and pass the absolute path above as the string argument to the + `--local-wix-dir` flag. For example: + ``` + fleetctl package --type msi --fleet-url=[YOUR FLEET URL] --enroll-secret=[YOUR ENROLLMENT SECRET] --local-wix-dir "\Users\me\AppData\Local\Temp\wix311-binaries" + ``` + If the provided path doesn't contain all 3 binaries, the command will fail. + +>**Note:** Creating a fleetd agent for Windows (.msi) on macOS also requires Wine. To install Wine see the script [here](https://github.com/fleetdm/fleet/blob/fleet-v4.44.0/scripts/macos-install-wine.sh). + +### Experimental features + +> Any features listed here are not recommended for use in production environments + +**Using `fleetd` without enrolling Orbit** + +*Only available in fleetd v1.15.1 on Linux and macOS* + +It is possible to generate a fleetd package that does not connect to Fleet by omitting the `--fleet-url` and `--enroll-secret` flags when building a package. + +This can be useful in situations where you would like to test using `fleetd` to manage osquery updates while still managing osquery command-line flags and extensions locally +but can result in a large volume of error logs. In fleetd v1.15.1, we added an experimental feature to reduce log chatter in this scenario. + +Applying the environmental variable `"FLEETD_SILENCE_ENROLL_ERROR"=1` on a host will silence fleetd enrollment errors if a `--fleet-url` is not present. +This variable is read at launch and will require a restart of the Orbit service if it is not set before installing `fleetd` v1.15.1. + + + + diff --git a/docs/Using Fleet/fleetctl-CLI.md b/docs/Using Fleet/fleetctl-CLI.md new file mode 100644 index 000000000..d83702e46 --- /dev/null +++ b/docs/Using Fleet/fleetctl-CLI.md @@ -0,0 +1,223 @@ +# fleetctl CLI + +fleetctl (pronounced "Fleet control") is a CLI tool for managing Fleet from the command line. fleetctl enables a GitOps workflow with Fleet. + +fleetctl also provides a quick way to work with all the data exposed by Fleet without having to use the Fleet UI or work directly with the Fleet API. + +
+
+
+
+## Installing fleetctl
+
+Install fleetctl with npm or download the binary from [GitHub](https://github.com/fleetdm/fleet/releases).
+
+```sh
+npm install -g fleetctl
+```
+
+### Upgrading fleetctl
+
+The easiest way to update fleetctl is by running the installation command again.
+
+```sh
+npm install -g fleetctl@latest
+```
+
+## Usage
+
+
+### Available commands
+
+
+Much of the functionality available in the Fleet UI is also available in `fleetctl`. You can run queries, add and remove users, generate agent (fleetd) installers to add new hosts, get information about existing hosts, and more!
+
+To see the available commands you can run:
+
+```sh
+> fleetctl --help
+```
+
+### Get more info about a command
+
+Each command has a help menu with additional information. To pull up the help menu, run `fleetctl Options: `pkg`(macOS),`msi`(Windows), `deb`(Debian based Linux), `rpm`(RHEL, CentOS, etc.) | -| --fleet-desktop | Include Fleet Desktop. | -| --enroll-secret | Enroll secret for authenticating to Fleet server | -| --fleet-url | URL (`host:port`) of Fleet server | -| --fleet-certificate | Path to server certificate bundle | -| --identifier | Identifier for package product (default: `com.fleetdm.orbit`) | -| --version | Version for package product (default: `0.0.3`) | -| --insecure | Disable TLS certificate verification (default: `false`) | -| --service | Install osquery with a persistence service (launchd, systemd, etc.) (default: `true`) | -| --sign-identity | Identity to use for macOS codesigning | -| --notarize | Whether to notarize macOS packages (default: `false`) | -| --disable-updates | Disable auto updates on the generated package (default: false) | -| --osqueryd-channel | Update channel of osqueryd to use (default: `stable`) | -| --orbit-channel | Update channel of Orbit to use (default: `stable`) | -| --desktop-channel | Update channel of desktop to use (default: `stable`) | -| --update-url | URL for update server (default: `https://tuf.fleetctl.com`) | -| --update-roots | Root key JSON metadata for update server (from fleetctl updates roots) | -| --use-system-configuration | Try to read --fleet-url and --enroll-secret using configuration in the host (currently only macOS profiles are supported) | -| --debug | Enable debug logging (default: `false`) | -| --verbose | Log detailed information when building the package (default: false) | -| --help, -h | show help (default: `false`) | - - -Fleet supports other methods for adding your hosts to Fleet, such as the [plain osquery binaries](#add-hosts-with-plain-osquery) or [Kolide Osquery Launcher](https://github.com/kolide/launcher/blob/master/docs/launcher.md#connecting-to-fleet). - -## Add hosts with plain osquery - -Osquery's [TLS API plugin](http://osquery.readthedocs.io/en/stable/deployment/remote/) lets you use the native osqueryd binaries to connect to Fleet. - -You can find various ways to install osquery on your hosts at https://osquery.io/downloads. Once you have installed osquery, you need to do three things on your hosts: - -- Set up your Fleet enroll secret. -- Provide the TLS certificate that osquery will use to communicate with Fleet. -- Configure and launch osqueryd. - -### Set up your Fleet enroll secret - -The enroll secret is a value that osquery provides to authenticate with Fleet. There are a few ways you can set the enroll secret on the hosts which you control. You can either set the value as - -- a value of an environment variable (a common name is `OSQUERY_ENROLL_SECRET`) -- the content of a local file (a common path is `/etc/osquery/enroll_secret`) - -The value of the environment variable or content of the file should be a secret shared between the osqueryd client and the Fleet server. This is osqueryd's passphrase which it uses to authenticate with Fleet, convincing Fleet that it is actually one of your hosts. The passphrase could be whatever you'd like, but it would be prudent to have the passphrase long, complex, mixed-case, etc. When you launch the Fleet server, you should specify this same value. - -If you use an environment variable for this, you can specify it with the `--enroll_secret_env` flag when you launch osqueryd. If you use a local file for this, you can specify its path with the `--enroll_secret_path` flag. - -To retrieve the enroll secret, use the "Add New Host" dialog in the Fleet UI or -`fleetctl get enroll_secret`). - -If your organization has a robust internal public key infrastructure (PKI) and you already deploy TLS client certificates to each host to uniquely identify them, then osquery supports an advanced authentication mechanism that takes advantage of this. Fleet can be fronted with a proxy that will perform the TLS client authentication. - -### Provide the TLS certificate that osquery will use to communicate with Fleet - -When Fleet uses a self-signed certificate, osquery agents will need a copy of that certificate in order to authenticate the Fleet server. If clients connect directly to the Fleet server, you can download the certificate through the Fleet UI. From the main dashboard (`/hosts/manage`), click **Add New Host** and **Fetch Certificate**. If Fleet is running behind a load-balancer that terminates TLS, you will have to talk to your system administrator about where to find this certificate. - -It is important that the CN of this certificate matches the hostname or IP that osqueryd clients will use to connect. - -Specify the path to this certificate with the `--tls_server_certs` flag when you launch osqueryd. - -### Configure and launch osquery - -In order for osquery to connect to the fleet server, there are some flags that need to be set: - -``` - --enroll_secret_path=/etc/osquery/enroll_secret - --tls_server_certs=/etc/osquery/fleet.crt - --tls_hostname=fleet.example.com - --host_identifier=uuid - --enroll_tls_endpoint=/api/osquery/enroll - --config_plugin=tls - --config_tls_endpoint=/api/osquery/config - --config_refresh=10 - --disable_distributed=false - --distributed_plugin=tls - --distributed_interval=10 - --distributed_tls_max_attempts=3 - --distributed_tls_read_endpoint=/api/osquery/distributed/read - --distributed_tls_write_endpoint=/api/osquery/distributed/write - --logger_plugin=tls - --logger_tls_endpoint=/api/osquery/log - --logger_tls_period=10 - ``` -These can be specified directly in the command line or saved to a flag file. - -#### Launching osqueryd using command-line flags - -Assuming that you are deploying your enroll secret in the file `/etc/osquery/enroll_secret` and your osquery server certificate is at `/etc/osquery/fleet.crt`, you could copy and paste the following command with the following flags (be sure to replace `fleet.acme.net` with the hostname or IP of your Fleet installation): - -``` -sudo osqueryd \ - --enroll_secret_path=/etc/osquery/enroll_secret \ - --tls_server_certs=/etc/osquery/fleet.crt \ - --tls_hostname=fleet.example.com \ - --host_identifier=uuid \ - --enroll_tls_endpoint=/api/osquery/enroll \ - --config_plugin=tls \ - --config_tls_endpoint=/api/osquery/config \ - --config_refresh=10 \ - --disable_distributed=false \ - --distributed_plugin=tls \ - --distributed_interval=10 \ - --distributed_tls_max_attempts=3 \ - --distributed_tls_read_endpoint=/api/osquery/distributed/read \ - --distributed_tls_write_endpoint=/api/osquery/distributed/write \ - --logger_plugin=tls \ - --logger_tls_endpoint=/api/osquery/log \ - --logger_tls_period=10 -``` - -If your osquery server certificate is deployed to a path that is not `/etc/osquery/fleet.crt`, be sure to update the `--tls_server_certs` flag. Similarly, if your enroll secret is in an environment variable that is not called `OSQUERY_ENROLL_SECRET`. Then, be sure to update the `--enroll_secret_env` environment variable. - -If your enroll secret is defined in a local file, specify the file's path with the `--enroll_secret_path` flag instead of using the `--enroll_secret_env` flag. - -#### Launching osqueryd using a flag file - -For your convenience, osqueryd supports putting all your flags into a single file. We suggest deploying this file to `/etc/osquery/fleet.flags`. If you've deployed the appropriate osquery flags to that path, you could simply launch osquery via: - -``` -osqueryd --flagfile=/etc/osquery/fleet.flags -``` - -When using a flag file on Windows, make sure that file paths in the flag file are absolute and not quoted. For example, in `C:\Program Files\osquery\osquery.flags`: - -``` ---tls_server_certs=C:\Program Files\osquery\fleet.pem ---enroll_secret_path=C:\Program Files\osquery\secret.txt -``` - -### Migrating from plain osquery to osquery installer - -The following is a strategy for migrating a plain osquery deployment. Unlike plain osquery, Fleet's -osquery installer supports the automatic updating of osquery on your hosts so that you don't have to -deploy a new package for every new osquery release. - -#### Generate installer - -``` -fleetctl package --type [pkg|msi|deb|rpm] --fleet-url [fleet-hostname:port] --enroll-secret [secret] -``` - -If you currently ship a certificate (`fleet.pem`), also include this in the generated package with -`--fleet-certificate [/path/to/fleet.pem]`. - -Fleet automatically manages most of the osquery flags to connect to the Fleet server. There's no -need to set any of the flags mentioned above in [Configure and launch osquery](#configure-and-launch-osquery). To -include other osquery flags, provide a flagfile when packaging with `--osquery-flagfile -[/path/to/osquery.flags]`. - -Test the installers on each platform before initiating the migration. - -#### Migrate - -Install the generated package using your standard deployment tooling (Chef, Puppet, etc.). At this -time, [uninstall the existing -osquery](https://blog.fleetdm.com/how-to-uninstall-osquery-f01cc49a37b9). - -If the existing enrolled hosts use `--host_identifier=uuid` (or the `uuid` setting for Fleet's -[osquery_host_identifier](https://fleetdm.com/docs/deploying/configuration#osquery-host-identifier)), the new -installation should appear as the same host in the Fleet UI. If other settings are used, duplicate -entries will appear in the Fleet UI. The older entries can be automatically cleaned up with the host -expiration setting. To configure this setting, in the Fleet UI, head to **Settings > Organization settings > Advanced options**. - -## Add Chromebooks with the Fleetd Chrome extension - -Visit the Google Admin console. In the navigation menu, visit Devices > Chrome > Apps & Extensions > Users & browsers. - -Select the relevant organizational unit, users, or group where you want the fleetd Chrome extension to be installed. - -In the bottom right, click the yellow "+" button and select "Add Chrome app or extension by ID." - -Visit your Fleet instance and select Hosts > Add Hosts and select ChromeOS in the popup modal. - -Enter the "Extension ID," "Installation URL," and "Policy for extensions" using the data provided in the modal. - -Under "Installation Policy", select "Force install". Under "Update URL", select "Installation URL (see above)". - -> For the fleetd Chrome extension to have full access to Chrome data, it must be force-installed by enterprise policy as per above - -## Grant full disk access to osquery on macOS -macOS does not allow applications to access all system files by default. If you are using MDM, which -is required to deploy these profiles, you -can deploy a "Privacy Preferences Policy Control" policy to grant Orbit or osquery that level of -access. This is necessary to query for files located in protected paths as well as to use event -tables that require access to the [EndpointSecurity -API](https://developer.apple.com/documentation/endpointsecurity#overview), such as *es_process_events*. - -### Creating the configuration profile -#### Obtaining identifiers -If you use plain osquery, instructions are [available here](https://osquery.readthedocs.io/en/stable/deployment/process-auditing/). - -On a system with osquery installed via the Fleet osquery installer (Orbit), obtain the -`CodeRequirement` of Orbit by running: - -``` -codesign -dr - /opt/orbit/bin/orbit/macos/stable/orbit -``` - -The output should be similar or identical to: - -``` -Executable=/opt/orbit/bin/orbit/macos/edge/orbit -designated => identifier "com.fleetdm.orbit" and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = "8VBZ3948LU" -``` - -> **NOTE:** Depending on the version of `fleetctl` used to package and install Orbit, as well as the update channel you've specified, the executable path may differ. -> Fleetctl versions <= 4.13.2 would install orbit to `/var/lib/orbit` instead of `/opt/orbit`. - -Note down the **executable path** and the entire **identifier**. - -Osqueryd will inherit the privileges from Orbit and does not need explicit permissions. - -#### Creating the profile -Depending on your MDM, this might be possible in the UI or require a custom profile. If your MDM has a feature to configure *Policy Preferences*, follow these steps: - -1. Configure the identifier type to “path.” -2. Paste the full path to Orbit as the identifier. -3. Paste the full code signing identifier into the Code requirement field. -4. Allow “Access all files.” Access to Downloads, Documents, etc., is inherited from this. - -If your MDM does not have built-in support for privacy preferences profiles, you can use -[PPPC-Utility](https://github.com/jamf/PPPC-Utility) to create a profile with those values, then upload it to -your MDM as a custom profile. - -#### Test the profile -Link the profile to a test group that contains at least one Mac. -Once the computer has received the profile, which you can verify by looking at *Profiles* in *System -Preferences*, run this query from Fleet: - -```sql -SELECT * FROM file WHERE path LIKE '/Users/%/Downloads/%%'; -``` - -If this query returns files, the profile was applied, as **Downloads** is a -protected location. You can now enjoy the benefits of osquery on all system files and start -using the **es_process_events** table! - -If this query does not return data, you can look at operating system logs to confirm whether or not full disk -access has been applied. - -See the last hour of logs related to TCC permissions with this command: - -`log show --predicate 'subsystem == "com.apple.TCC"' --info --last 1h` - -You can then look for `orbit` or `osquery` to narrow down results. - - diff --git a/docs/Using-Fleet/Application-security.md b/docs/Using-Fleet/Application-security.md deleted file mode 100644 index d9dbe8e9b..000000000 --- a/docs/Using-Fleet/Application-security.md +++ /dev/null @@ -1,69 +0,0 @@ -# Application security - -- [Describe your secure coding practices (SDLC)](#describe-your-secure-coding-practices-including-code-reviews-use-of-staticdynamic-security-testing-tools-3rd-party-scansreviews) -- [SQL injection](#sql-injection) -- [Broken authentication](#broken-authentication--authentication-session-management-flaws-that-compromise-passwords-keys-session-tokens-etc) - - [Passwords](#passwords) - - [Authentication tokens](#authentication-tokens) -- [Sensitive data exposure](#sensitive-data-exposure--encryption-in-transit-at-rest-improperly-implemented-APIs) -- [Cross-site scripting](#cross-site-scripting--ensure-an-attacker-cant-execute-scripts-in-the-users-browser) -- [Components with known vulnerabilities](#components-with-known-vulnerabilities--prevent-the-use-of-libraries-frameworks-other-software-with-existing-vulnerabilities) - -The Fleet community follows best practices when coding. Here are some of the ways we mitigate against the OWASP top 10 issues: - -### Describe your secure coding practices, including code reviews, use of static/dynamic security testing tools, 3rd party scans/reviews. - -Code commits to Fleet go through a series of tests, including SAST (static application security -testing). We use a combination of tools, including [gosec](https://github.com/securego/gosec) and -[CodeQL](https://codeql.github.com/) for this purpose. - -At least one other engineer reviews every piece of code before merging it to Fleet. -This is enforced via branch protection on the main branch. - -The server backend is built in Golang, which (besides for language-level vulnerabilities) eliminates buffer overflow and other memory related attacks. - -We use standard library cryptography wherever possible, and all cryptography is using well-known standards. - -### SQL injection - -All queries are parameterized with MySQL placeholders, so MySQL itself guards against SQL injection and the Fleet code does not need to perform any escaping. - -### Broken authentication – authentication, session management flaws that compromise passwords, keys, session tokens etc. - -#### Passwords - -Fleet supports SAML auth which means that it can be configured such that it never sees passwords. - -Passwords are never stored in plaintext in the database. We store a `bcrypt`ed hash of the password along with a randomly generated salt. The `bcrypt` iteration count and salt key size are admin-configurable. - -#### Authentication tokens - -The size and expiration time of session tokens is admin-configurable. See [The documentation on session duration](https://fleetdm.com/docs/deploying/configuration#session-duration). - -It is possible to revoke all session tokens for a user by forcing a password reset. - -### Sensitive data exposure – encryption in transit, at rest, improperly implemented APIs. - -By default, all traffic between user clients (such as the web browser and fleetctl) and the Fleet server is encrypted with TLS. By default, all traffic between osqueryd clients and the Fleet server is encrypted with TLS. Fleet does not by itself encrypt any data at rest (_however a user may separately configure encryption for the MySQL database and logs that Fleet writes_). - -### Broken access controls – how restrictions on what authorized users are allowed to do/access are enforced. - -Each session is associated with a viewer context that is used to determine the access granted to that user. Access controls can easily be applied as middleware in the routing table, so the access to a route is clearly defined in the same place where the route is attached to the server see [https://github.com/fleetdm/fleet/blob/main/server/service/handler.go#L114-L189](https://github.com/fleetdm/fleet/blob/main/server/service/handler.go#L114-L189). - -### Cross-site scripting – ensure an attacker can’t execute scripts in the user’s browser - -We render the frontend with React and benefit from built-in XSS protection in React's rendering. This is not sufficient to prevent all XSS, so we also follow additional best practices as discussed in [https://stackoverflow.com/a/51852579/491710](https://stackoverflow.com/a/51852579/491710). - -### Components with known vulnerabilities – prevent the use of libraries, frameworks, other software with existing vulnerabilities. - -We rely on GitHub's automated vulnerability checks, community news, and direct reports to discover -vulnerabilities in our dependencies. We endeavor to fix these immediately and would almost always do -so within a week of a report. - -Libraries are inventoried and monitored for vulnerabilities. Our process for fixing vulnerable -libraries and other vulnerabilities is available in our -[handbook](https://fleetdm.com/handbook/security#vulnerability-management). We use -[Dependabot](https://github.com/dependabot) to automatically open PRs to update vulnerable dependencies. - - - diff --git a/docs/Using-Fleet/Audit-Activities.md b/docs/Using-Fleet/Audit-Activities.md deleted file mode 100644 index a04249c3b..000000000 --- a/docs/Using-Fleet/Audit-Activities.md +++ /dev/null @@ -1,829 +0,0 @@ - -# Audit Activities - -Fleet logs the following information for administrative actions (in JSON): - -- `created_at`: Timestamp of the event. -- `id`: Unique ID of the generated event in Fleet. -- `actor_full_name`: Author user name (missing if the user was deleted). -- `actor_id`: Unique ID of the author in Fleet (missing if the user was deleted). -- `actor_gravatar`: Gravatar URL of the author (missing if the user was deleted). -- `actor_email`: E-mail of the author (missing if the user was deleted). -- `type`: Type of the activity (see all types below). -- `details`: Specific details depending on the type of activity (see details for each activity type below). - -Example: -```json -{ - "created_at": "2022-12-20T14:54:17Z", - "id": 6, - "actor_full_name": "Gandalf", - "actor_id": 2, - "actor_gravatar": "foo@example.com", - "actor_email": "foo@example.com", - "type": "edited_saved_query", - "details":{ - "query_id": 42, - "query_name": "Some query name" - } -} -``` - -## List of activities and their specific details - -### Type `created_pack` - -Generated when creating scheduled query packs. - -This activity contains the following fields: -- "pack_id": the id of the created pack. -- "pack_name": the name of the created pack. - -#### Example - -```json -{ - "pack_id": 123, - "pack_name": "foo" -} -``` - -### Type `edited_pack` - -Generated when editing scheduled query packs. - -This activity contains the following fields: -- "pack_id": the id of the edited pack. -- "pack_name": the name of the edited pack. - -#### Example - -```json -{ - "pack_id": 123, - "pack_name": "foo" -} -``` - -### Type `deleted_pack` - -Generated when deleting scheduled query packs. - -This activity contains the following fields: -- "pack_name": the name of the created pack. - -#### Example - -```json -{ - "pack_name": "foo" -} -``` - -### Type `applied_spec_pack` - -Generated when applying a scheduled query pack spec. - -This activity does not contain any detail fields. - -### Type `created_policy` - -Generated when creating policies. - -This activity contains the following fields: -- "policy_id": the ID of the created policy. -- "policy_name": the name of the created policy. - -#### Example - -```json -{ - "policy_id": 123, - "policy_name": "foo" -} -``` - -### Type `edited_policy` - -Generated when editing policies. - -This activity contains the following fields: -- "policy_id": the ID of the edited policy. -- "policy_name": the name of the edited policy. - -#### Example - -```json -{ - "policy_id": 123, - "policy_name": "foo" -} -``` - -### Type `deleted_policy` - -Generated when deleting policies. - -This activity contains the following fields: -- "policy_id": the ID of the deleted policy. -- "policy_name": the name of the deleted policy. - -#### Example - -```json -{ - "policy_id": 123, - "policy_name": "foo" -} -``` - -### Type `applied_spec_policy` - -Generated when applying policy specs. - -This activity contains a field "policies" where each item is a policy spec with the following fields: -- "name": Name of the applied policy. -- "query": SQL query of the policy. -- "description": Description of the policy. -- "critical": Marks the policy as high impact. -- "resolution": Describes how to solve a failing policy. -- "team": Name of the team this policy belongs to. -- "platform": Comma-separated string to indicate the target platforms. - - -#### Example - -```json -{ - "policies": [ - { - "name":"Gatekeeper enabled (macOS)", - "query":"SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;", - "critical":false, - "platform":"darwin", - "resolution":"To enable Gatekeeper, on the failing device [...]", - "description":"Checks to make sure that the Gatekeeper feature is [...]" - }, - { - "name":"Full disk encryption enabled (Windows)", - "query":"SELECT 1 FROM bitlocker_info WHERE drive_letter='C:' AND protection_status=1;", - "critical":false, - "platform":"windows", - "resolution":"To get additional information, run the following osquery [...]", - "description":"Checks to make sure that full disk encryption is enabled on Windows devices." - } - ] -} -``` - -### Type `created_saved_query` - -Generated when creating a new query. - -This activity contains the following fields: -- "query_id": the ID of the created query. -- "query_name": the name of the created query. - -#### Example - -```json -{ - "query_id": 123, - "query_name": "foo" -} -``` - -### Type `edited_saved_query` - -Generated when editing a saved query. - -This activity contains the following fields: -- "query_id": the ID of the query being edited. -- "query_name": the name of the query being edited. - -#### Example - -```json -{ - "query_id": 123, - "query_name": "foo" -} -``` - -### Type `deleted_saved_query` - -Generated when deleting a saved query. - -This activity contains the following fields: -- "query_name": the name of the query being deleted. - -#### Example - -```json -{ - "query_name": "foo" -} -``` - -### Type `deleted_multiple_saved_query` - -Generated when deleting multiple saved queries. - -This activity contains the following fields: -- "query_ids": list of IDs of the deleted saved queries. - -#### Example - -```json -{ - "query_ids": [1, 42, 100] -} -``` - -### Type `applied_spec_saved_query` - -Generated when applying a query spec. - -This activity contains a field "specs" where each item is a query spec with the following fields: -- "name": Name of the query. -- "description": Description of the query. -- "query": SQL query. - -#### Example - -```json -{ - "specs": [ - { - "name":"Get OpenSSL versions", - "query":"SELECT name AS name, version AS version, 'deb_packages' AS source FROM [...]", - "description":"Retrieves the OpenSSL version." - } - ] -} -``` - -### Type `created_team` - -Generated when creating teams. - -This activity contains the following fields: -- "team_id": unique ID of the created team. -- "team_name": the name of the created team. - -#### Example - -```json -{ - "team_id": 123, - "team_name": "foo" -} -``` - -### Type `deleted_team` - -Generated when deleting teams. - -This activity contains the following fields: -- "team_id": unique ID of the deleted team. -- "team_name": the name of the deleted team. - -#### Example - -```json -{ - "team_id": 123, - "team_name": "foo" -} -``` - -### Type `applied_spec_team` - -Generated when applying team specs. - -This activity contains a field "teams" where each item contains the team details with the following fields: -- "id": Unique ID of the team. -- "name": Name of the team. - -#### Example - -```json -{ - "teams": [ - { - "id": 123, - "name": "foo" - } - ] -} -``` - -### Type `transferred_hosts` - -Generated when a user transfers a host (or multiple hosts) to a team (or no team). - -This activity contains the following fields: -- "team_id": The ID of the team that the hosts were transferred to, `null` if transferred to no team. -- "team_name": The name of the team that the hosts were transferred to, `null` if transferred to no team. -- "host_ids": The list of identifiers of the hosts that were transferred. -- "host_display_names": The list of display names of the hosts that were transferred (in the same order as the "host_ids"). - -#### Example - -```json -{ - "team_id": 123, - "team_name": "Workstations", - "host_ids": [1, 2, 3], - "host_display_names": ["alice-macbook-air", "bob-macbook-pro", "linux-server"] -} -``` - -### Type `edited_agent_options` - -Generated when agent options are edited (either globally or for a team). - -This activity contains the following fields: -- "global": "true" if the user updated the global agent options, "false" if the agent options of a team were updated. -- "team_id": unique ID of the team for which the agent options were updated (`null` if global is true). -- "team_name": the name of the team for which the agent options were updated (`null` if global is true). - -#### Example - -```json -{ - "team_id": 123, - "team_name": "foo", - "global": false -} -``` - -### Type `live_query` - -Generated when running live queries. - -This activity contains the following fields: -- "targets_count": Number of hosts where the live query was targeted to run. -- "query_sql": The SQL query to run on hosts. -- "query_name": Name of the query (this field is not set if this was not a saved query). - -#### Example - -```json -{ - "targets_count": 5000, - "query_sql": "SELECT * from osquery_info;", - "query_name": "foo" -} -``` - -### Type `user_added_by_sso` - -Generated when new users are added via SSO JIT provisioning - -This activity does not contain any detail fields. - -### Type `user_logged_in` - -Generated when users successfully log in to Fleet. - -This activity contains the following fields: -- "public_ip": Public IP of the login request. - -#### Example - -```json -{ - "public_ip": "168.226.215.82" -} -``` - -### Type `user_failed_login` - -Generated when users try to log in to Fleet and fail. - -This activity contains the following fields: -- "email": The email used in the login request. -- "public_ip": Public IP of the login request. - -#### Example - -```json -{ - "email": "foo@example.com", - "public_ip": "168.226.215.82" -} -``` - -### Type `created_user` - -Generated when a user is created. - -This activity contains the following fields: -- "user_id": Unique ID of the created user in Fleet. -- "user_name": Name of the created user. -- "user_email": E-mail of the created user. - -#### Example - -```json -{ - "user_id": 42, - "user_name": "Foo", - "user_email": "foo@example.com" -} -``` - -### Type `deleted_user` - -Generated when a user is deleted. - -This activity contains the following fields: -- "user_id": Unique ID of the deleted user in Fleet. -- "user_name": Name of the deleted user. -- "user_email": E-mail of the deleted user. - -#### Example - -```json -{ - "user_id": 42, - "user_name": "Foo", - "user_email": "foo@example.com" -} -``` - -### Type `changed_user_global_role` - -Generated when user global roles are changed. - -This activity contains the following fields: -- "user_id": Unique ID of the edited user in Fleet. -- "user_name": Name of the edited user. -- "user_email": E-mail of the edited user. -- "role": New global role of the edited user. - -#### Example - -```json -{ - "user_id": 42, - "user_name": "Foo", - "user_email": "foo@example.com", - "role": "Observer" -} -``` - -### Type `deleted_user_global_role` - -Generated when user global roles are deleted. - -This activity contains the following fields: -- "user_id": Unique ID of the edited user in Fleet. -- "user_name": Name of the edited user. -- "user_email": E-mail of the edited user. -- "role": Deleted global role of the edited user. - -#### Example - -```json -{ - "user_id": 43, - "user_name": "Foo", - "user_email": "foo@example.com", - "role": "Maintainer" -} -``` - -### Type `changed_user_team_role` - -Generated when user team roles are changed. - -This activity contains the following fields: -- "user_id": Unique ID of the edited user in Fleet. -- "user_name": Name of the edited user. -- "user_email": E-mail of the edited user. -- "role": Team role set to the edited user. -- "team_id": Unique ID of the team of the changed role. -- "team_name": Name of the team of the changed role. - -#### Example - -```json -{ - "user_id": 43, - "user_name": "Foo", - "user_email": "foo@example.com", - "role": "Maintainer", - "team_id": 5, - "team_name": "Bar" -} -``` - -### Type `deleted_user_team_role` - -Generated when user team roles are deleted. - -This activity contains the following fields: -- "user_id": Unique ID of the edited user in Fleet. -- "user_name": Name of the edited user. -- "user_email": E-mail of the edited user. -- "role": Team role deleted from the edited user. -- "team_id": Unique ID of the team of the deleted role. -- "team_name": Name of the team of the deleted role. - -#### Example - -```json -{ - "user_id": 44, - "user_name": "Foo", - "user_email": "foo@example.com", - "role": "Observer", - "team_id": 2, - "team_name": "Zoo" -} -``` - -### Type `mdm_enrolled` - -Generated when a host is enrolled in Fleet's MDM. - -This activity contains the following fields: -- "host_serial": Serial number of the host. -- "host_display_name": Display name of the host. -- "installed_from_dep": Whether the host was enrolled via DEP. - -#### Example - -```json -{ - "host_serial": "C08VQ2AXHT96", - "host_display_name": "MacBookPro16,1 (C08VQ2AXHT96)", - "installed_from_dep": true -} -``` - -### Type `mdm_unenrolled` - -Generated when a host is unenrolled from Fleet's MDM. - -This activity contains the following fields: -- "host_serial": Serial number of the host. -- "host_display_name": Display name of the host. -- "installed_from_dep": Whether the host was enrolled via DEP. - -#### Example - -```json -{ - "host_serial": "C08VQ2AXHT96", - "host_display_name": "MacBookPro16,1 (C08VQ2AXHT96)", - "installed_from_dep": true -} -``` - -### Type `edited_macos_min_version` - -Generated when the minimum required macOS version or deadline is modified. - -This activity contains the following fields: -- "team_id": The ID of the team that the minimum macOS version applies to, `null` if it applies to devices that are not in a team. -- "team_name": The name of the team that the minimum macOS version applies to, `null` if it applies to devices that are not in a team. -- "minimum_version": The minimum macOS version required, empty if the requirement was removed. -- "deadline": The deadline by which the minimum version requirement must be applied, empty if the requirement was removed. - -#### Example - -```json -{ - "team_id": 3, - "team_name": "Workstations", - "minimum_version": "13.0.1", - "deadline": "2023-06-01" -} -``` - -### Type `read_host_disk_encryption_key` - -Generated when a user reads the disk encryption key for a host. - -This activity contains the following fields: -- "host_id": ID of the host. -- "host_display_name": Display name of the host. - -#### Example - -```json -{ - "host_id": 1, - "host_display_name": "Anna's MacBook Pro", -} -``` - -### Type `created_macos_profile` - -Generated when a user adds a new macOS profile to a team (or no team). - -This activity contains the following fields: -- "profile_name": Name of the profile. -- "profile_identifier": Identifier of the profile. -- "team_id": The ID of the team that the profile applies to, `null` if it applies to devices that are not in a team. -- "team_name": The name of the team that the profile applies to, `null` if it applies to devices that are not in a team. - -#### Example - -```json -{ - "profile_name": "Custom settings 1", - "profile_identifier": "com.my.profile", - "team_id": 123, - "team_name": "Workstations" -} -``` - -### Type `deleted_macos_profile` - -Generated when a user deletes a macOS profile from a team (or no team). - -This activity contains the following fields: -- "profile_name": Name of the deleted profile. -- "profile_identifier": Identifier of deleted the profile. -- "team_id": The ID of the team that the profile applied to, `null` if it applied to devices that are not in a team. -- "team_name": The name of the team that the profile applied to, `null` if it applied to devices that are not in a team. - -#### Example - -```json -{ - "profile_name": "Custom settings 1", - "profile_identifier": "com.my.profile", - "team_id": 123, - "team_name": "Workstations" -} -``` - -### Type `edited_macos_profile` - -Generated when a user edits the macOS profiles of a team (or no team) via the fleetctl CLI. - -This activity contains the following fields: -- "team_id": The ID of the team that the profiles apply to, `null` if they apply to devices that are not in a team. -- "team_name": The name of the team that the profiles apply to, `null` if they apply to devices that are not in a team. - -#### Example - -```json -{ - "team_id": 123, - "team_name": "Workstations" -} -``` - -### Type `changed_macos_setup_assistant` - -Generated when a user sets the macOS setup assistant for a team (or no team). - -This activity contains the following fields: -- "name": Name of the macOS setup assistant file. -- "team_id": The ID of the team that the setup assistant applies to, `null` if it applies to devices that are not in a team. -- "team_name": The name of the team that the setup assistant applies to, `null` if it applies to devices that are not in a team. - -#### Example - -```json -{ - "name": "dep_profile.json", - "team_id": 123, - "team_name": "Workstations" -} -``` - -### Type `deleted_macos_setup_assistant` - -Generated when a user deletes the macOS setup assistant for a team (or no team). - -This activity contains the following fields: -- "name": Name of the deleted macOS setup assistant file. -- "team_id": The ID of the team that the setup assistant applied to, `null` if it applied to devices that are not in a team. -- "team_name": The name of the team that the setup assistant applied to, `null` if it applied to devices that are not in a team. - -#### Example - -```json -{ - "name": "dep_profile.json", - "team_id": 123, - "team_name": "Workstations" -} -``` - -### Type `enabled_macos_disk_encryption` - -Generated when a user turns on macOS disk encryption for a team (or no team). - -This activity contains the following fields: -- "team_id": The ID of the team that disk encryption applies to, `null` if it applies to devices that are not in a team. -- "team_name": The name of the team that disk encryption applies to, `null` if it applies to devices that are not in a team. - -#### Example - -```json -{ - "team_id": 123, - "team_name": "Workstations" -} -``` - -### Type `disabled_macos_disk_encryption` - -Generated when a user turns off macOS disk encryption for a team (or no team). - -This activity contains the following fields: -- "team_id": The ID of the team that disk encryption applies to, `null` if it applies to devices that are not in a team. -- "team_name": The name of the team that disk encryption applies to, `null` if it applies to devices that are not in a team. - -#### Example - -```json -{ - "team_id": 123, - "team_name": "Workstations" -} -``` - -### Type `added_bootstrap_package` - -Generated when a user adds a new bootstrap package to a team (or no team). - -This activity contains the following fields: -- "package_name": Name of the package. -- "team_id": The ID of the team that the package applies to, `null` if it applies to devices that are not in a team. -- "team_name": The name of the team that the package applies to, `null` if it applies to devices that are not in a team. - -#### Example - -```json -{ - "bootstrap_package_name": "bootstrap-package.pkg", - "team_id": 123, - "team_name": "Workstations" -} -``` - -### Type `deleted_bootstrap_package` - -Generated when a user deletes a bootstrap package from a team (or no team). - -This activity contains the following fields: -- "package_name": Name of the package. -- "team_id": The ID of the team that the package applies to, `null` if it applies to devices that are not in a team. -- "team_name": The name of the team that the package applies to, `null` if it applies to devices that are not in a team. - -#### Example - -```json -{ - "package_name": "bootstrap-package.pkg", - "team_id": 123, - "team_name": "Workstations" -} -``` - -### Type `enabled_macos_setup_end_user_auth` - -Generated when a user turns on end user authentication for macOS hosts that automatically enroll to a team (or no team). - -This activity contains the following fields: -- "team_id": The ID of the team that end user authentication applies to, `null` if it applies to devices that are not in a team. -- "team_name": The name of the team that end user authentication applies to, `null` if it applies to devices that are not in a team. - -#### Example - -```json -{ - "team_id": 123, - "team_name": "Workstations" -} -``` - -### Type `disabled_macos_setup_end_user_auth` - -Generated when a user turns off end user authentication for macOS hosts that automatically enroll to a team (or no team). - -This activity contains the following fields: -- "team_id": The ID of the team that end user authentication applies to, `null` if it applies to devices that are not in a team. -- "team_name": The name of the team that end user authentication applies to, `null` if it applies to devices that are not in a team. - -#### Example - -```json -{ - "team_id": 123, - "team_name": "Workstations" -} -``` - - - - \ No newline at end of file diff --git a/docs/Using-Fleet/CIS-Benchmarks.md b/docs/Using-Fleet/CIS-Benchmarks.md deleted file mode 100644 index 65b69cc10..000000000 --- a/docs/Using-Fleet/CIS-Benchmarks.md +++ /dev/null @@ -1,260 +0,0 @@ -# CIS Benchmarks - -## Overview -CIS Benchmarks represent the consensus-based effort of cybersecurity experts globally to help you protect your systems against threats more confidently. -For more information about CIS Benchmarks check out [Center for Internet Security](https://www.cisecurity.org/cis-benchmarks)'s website. - -Fleet has implemented native support for CIS benchmarks for the following platforms: -- macOS 13.0 Ventura (96 checks) -- Windows 10 Enterprise (496 checks) - -[Where possible](#limitations), each CIS benchmark is implemented with a [policy query](./REST-API.md#policies) in Fleet. - -## Requirements - -Following are the requirements to use the CIS Benchmarks in Fleet: - -- Fleet must be Premium or Ultimate licensed. -- Devices must be running [Fleetd](https://fleetdm.com/docs/using-fleet/orbit), the osquery manager from Fleet. -- Devices must be enrolled to an MDM solution. -- On macOS, the orbit executable in Fleetd must have "Full Disk Access", see [Grant Full Disk Access to Osquery on macOS](./Adding-hosts.md#grant-full-disk-access-to-osquery-on-macos). - -### MDM required -Some of the policies created by Fleet use the [managed_policies](https://www.fleetdm.com/tables/managed_policies) table. This checks whether an MDM solution has turned on the setting to enforce the policy. -Using MDM is the recommended way to manage and enforce CIS benchmarks. To learn how to set up MDM in Fleet, visit [here](/docs/using-fleet/mdm-setup). - -### Fleetd required -Fleet's CIS benchmarks require our [osquery manager, Fleetd](https://fleetdm.com/docs/using-fleet/adding-hosts#osquery-installer). This is because Fleetd includes tables which are not part of vanilla osquery in order to accomplish auditing the benchmarks. - -## How to add CIS benchmarks - -All CIS policies are stored under our restricted licensed folder `ee/cis/`. - -How to import them to Fleet: -```sh -# Download policy queries from Fleet's repository -# macOS 13 -wget https://raw.githubusercontent.com/fleetdm/fleet/main/ee/cis/macos-13/cis-policy-queries.yml - -# Windows 10 (note the same file name. Rename as needed.) -wget https://raw.githubusercontent.com/fleetdm/fleet/main/ee/cis/win-10/cis-policy-queries.yml - -# Apply the downloaded policies to Fleet for both files. -fleetctl apply --context
-
-
-
-## Create a query
-
-Queries in Fleet allow you to ask a multitude of questions to help you manage, monitor, and identify threats on your devices.
-
-If you're unsure of what to ask, head to Fleet's [query library](https://fleetdm.com/queries). There you'll find common queries that have been tested by members of our community.
-
-How to create a query:
-
-1. In the top navigation, select **Queries**.
-
-2. Select **Create new query** to navigate to the query console.
-
-3. In the **Query** field, enter your query. Remember, you can find common queries in [Fleet's library](https://fleetdm.com/queries).
-
-4. Select **Save**, enter a name and description for your query, and select **Save query**.
-
-## Run a query
-
-Run a live query to get answers for all of your online hosts.
-
-> Offline hosts won’t respond to a live query because they may be shut down, asleep, or not connected to the internet.
-
-How to run a query:
-
-1. In the top navigation, select **Queries**.
-
-2. In the **Queries** table, find the query you'd like to run and select the query's name to navigate to the query console.
-
-3. Select **Run query** to navigate to the target picker. Select **All hosts** and select **Run**. This will run the query against all your hosts.
-
-The query may take several seconds to complete because Fleet has to wait for the hosts to respond with results.
-
-> Fleet's query response time is inherently variable because of osquery's heartbeat response time. This helps prevent performance issues on hosts.
-
-## Schedule a query
-
-Fleet allows you to schedule queries. Scheduled queries will send data to your log destination automatically.
-
-The default log destination, **filesystem**, is good to start. With this set, data is sent to the `/var/log/osquery/osqueryd.snapshots.log` file on each host’s filesystem. To see which log destinations are available in Fleet, head to the [log destinations page](https://fleetdm.com/docs/using-fleet/log-destinations).
-
-How to schedule a query:
-
-1. In the top navigation, select **Schedule**.
-
-2. Select **Schedule a query**.
-
-3. Select the **Select query** dropdown and choose the query that you'd like to run on a schedule.
-
-4. Select the **Frequency** dropdown and choose how often you'd like the query to run and send results to your log destination. **Every hour** is a good frequency to start. You can change this later.
-
-5. Select **Schedule**.
-
-With Fleet Premium, you can schedule queries for groups of hosts using [the teams feature](https://fleetdm.com/docs/using-fleet/teams). This allows you to collect different data for each group.
-
-> In Fleet Premium, groups of hosts are called "teams."
-
-How to use teams to schedule queries for a group of hosts:
-
-1. If you haven't already, first [create a team](https://fleetdm.com/docs/using-fleet/teams#create-a-team) and [transfer hosts](https://fleetdm.com/docs/using-fleet/teams#transfer-hosts-to-a-team) to the team.
-
-2. In the **Teams** dropdown below the top navigation, select the team.
-
-3. Follow the "How to schedule a query" instructions above.
-
-## Update agent options
-
-
-
-
-Fleet allows you to update the settings of the agent installed on all your hosts at once. In Fleet, these settings are called "agent options."
-
-The default agent options are good to start.
-
-How to update agent options:
-
-1. In the top navigation, select your avatar and select **Settings**. Only users with the [admin role](https://fleetdm.com/docs/using-fleet/permissions) can access the pages in **Settings**.
-
-2. On the Organization settings page, select **Agent options** on the left side of the page.
-
-3. Use Fleet's YAML editor to configure your osquery options, decorators, or set command line flags.
-
-To see all agent options, head to the [agent options documentation](https://fleetdm.com/docs/using-fleet/configuration-files#agent-options).
-
-4. Place your new setting one level below the `options` key. The new setting's key should be below and one tab to the right of `options`.
-
-5. Select **Save**.
-
-The agents may take several seconds to update because Fleet has to wait for the hosts to check in. Additionally, hosts enrolled with removed enroll secrets must properly rotate their secret to have the new changes take effect.
-
-
-
-
diff --git a/docs/Using-Fleet/MDM-commands.md b/docs/Using-Fleet/MDM-commands.md
deleted file mode 100644
index 179285118..000000000
--- a/docs/Using-Fleet/MDM-commands.md
+++ /dev/null
@@ -1,120 +0,0 @@
-# Commands
-
-In Fleet you can run MDM commands to take some action on your macOS hosts, like restart the host, remotely.
-
-If a host is offline when you run a command, the host will run the command the next time it comes online.
-
-## Custom commands
-
-You can run custom commands and view a specific command's results using the `fleetctl` command-line interface.
-
-To run a custom command, we will do the following steps:
-1. Create a `.xml` with the request payload
-2. Choose a target host
-3. Run the command using `fleetctl`
-4. View our command's results using `fleetctl`
-
-### Step 1: create a `.xml` file
-
-You can run any command supported by Apple's MDM protocol as a custom command in Fleet. To see the list of possible commands, head to [Apple's Commands and Queries documentation](https://developer.apple.com/documentation/devicemanagement/commands_and_queries).
-
-> The "Erase a device" and "Lock a device" commands are only available in Fleet Premium
-
-Each command has example request payloads in XML format. For example, if we want to restart a host, we'll use the "Restart a Device" request payload documented by Apple [here](https://developer.apple.com/documentation/devicemanagement/restart_a_device#3384428).
-
-To run the "Restart a device" command, we'll need to create a `restart-device.xml` file locally and copy and paste the request payload into this `.xml` file:
-
-```xml
-
-
-
-
-#### Automatic Enrollment (ADE)
-
-1. If your device is enrolled in Apple Business Manager (ABM) and assigned to the Fleet server, the end user will receive a "Device Enrollment: <organization> can automatically configure your Mac." system notification within the macOS Notifications Center.
-
-2. After the end user clicks on the system notification, macOS will open the "Profiles" System Setting and ask the user to "Allow Device Enrollment: <organization> can automatically configure your Mac based on settings provided by your System Administrator."
-
-3. If the end user does not Allow the setting, the system notification will continue to nag the end user until the setting has been allowed.
-
-4. Once this setting has been approved, the MDM enrollment profile cannot be removed by the end user.
-
-#### Manual Enrollment
-
-1. If your device is not enrolled in Apple Business Manager (ABM), the end user will be given the option to manually download the MDM enrollment profile.
-
-2. Once downloaded, the user will receive a system notification that the Device Enrollment profile has been needs to be installed in the System Settings > Profiles section.
-
-2. After installation, the MDM enrollment profile can be removed by the end user at any time.
-
-### How to turn on disk encryption
-
-1. Select the Fleet icon in your menu bar and select **My device**.
-
-
-
-2. On your **My device** page, follow the disk encryption instructions in the yellow banner.
- - If you don’t see the yellow banner, select the purple **Refetch** button at the top of the page.
- - If you still don't see the yellow banner after a couple minutes or if the **My device** page presents you with an error, please contact your IT administrator.
-
-
-
-
-
diff --git a/docs/Using-Fleet/MDM-setup.md b/docs/Using-Fleet/MDM-setup.md
deleted file mode 100644
index 54f742054..000000000
--- a/docs/Using-Fleet/MDM-setup.md
+++ /dev/null
@@ -1,284 +0,0 @@
-# MDM setup
-
-## Supported macOS versions
-
-macOS 12 (Monterey) and higher.
-
-## Overview
-
-MDM features require Apple's Push Notification service (APNs) to control and secure Apple devices. This guide will walk you through how to generate and upload a valid APNs certificate to Fleet in order to use Fleet's MDM features.
-
-[Automated Device Enrollment](https://support.apple.com/en-us/HT204142) allows Macs to automatically enroll to Fleet when they are first set up. This guide will also walk you through how to connect Apple Business Manager (ABM) to Fleet.
-
-> **Note** you are only required to connect Apple Business Manager (ABM) to Fleet if you are using Automated Device Enrollment AKA Device Enrollment Program (DEP) AKA "Zero-touch."
-
-## Requirements
-To use Fleet's MDM features you need to have:
-- A [deployed Fleet instance](../Deploying/Introduction.md).
-- A Fleet user with the admin role.
-
-## Apple Push Notification service (APNs)
-Apple uses APNs to authenticate and manage interactions between Fleet and the host.
-
-This section will show you how to:
-1. Generate the files to connect Fleet to APNs.
-2. Generate an APNs certificate from Apple Push Certificates Portal.
-3. Configure Fleet with the required files.
-
-### Step 1: generate the required files
-For the MDM protocol to function, we need to generate the four following files:
-- APNs certificate
-- APNs private key
-- Simple Certificate Enrollment Protocol (SCEP) certificate
-- SCEP private key
-
-The APNs certificates serve as authentication between Fleet and Apple, while the SCEP certificates serve as authentication between Fleet and hosts.
-
-Use either of the following methods to generate the necessary files:
-
-#### Fleet UI
-
-1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
-2. Under **Apple Push Certificates Portal**, select **Request**, then fill out the form. This should generate three files and send an email to you with an attached CSR file.
-
-#### Fleetctl CLI
-
-Run the following command to download three files and send an email to you with an attached CSR file.
-
-```
-fleetctl generate mdm-apple --email (default: tuf.fleetctl.com)"]; - fleet_server[Fleet
Server]; - - subgraph Orbit Agent - orbit[orbit]; - desktop[Fleet Desktop
Tray App]; - osqueryd[osqueryd]; - - desktop_browser[Fleet Desktop
from Browser]; - end - - orbit -- "Fleet Orbit API (TLS)" --> fleet_server; - desktop -- "Fleet Desktop API (TLS)" --> fleet_server; - osqueryd -- "osquery
remote API (TLS)" --> fleet_server; - desktop_browser -- "My Device API (TLS)" --> fleet_server; - - orbit -- "Auto Update (TLS)" --> tuf; -``` - -## Try Orbit - -#### With [`fleetctl preview` already running](https://github.com/fleetdm/fleet#try-fleet): - -```bash -# With fleetctl in your $PATH -# Generate a macOS installer pointed at your local Fleet -fleetctl package --type=pkg --fleet-url=localhost:8412 --insecure --enroll-secret=YOUR_FLEET_ENROLL_SECRET_HERE -``` - -> With fleetctl preview running, you can find your Fleet enroll secret by selecting the "Add new host" button on the Hosts page in the Fleet UI. - -An installer configured to point at your Fleet instance has now been generated. - -Now run that installer (double click, on a Mac) to enroll your own computer as a host in Fleet. Refresh after several seconds (≈30s), and you should now see your local computer as a new host in Fleet. - -## Capabilities - -| Capability | Status | -| ------------------------------------ | ------ | -| Secure autoupdate for osquery | ✅ | -| Secure autoupdate for Orbit | ✅ | -| Configurable update channels | ✅ | -| Full osquery flag customization | ✅ | -| Package tooling for macOS `.pkg` | ✅ | -| Package tooling for Linux `.deb` | ✅ | -| Package tooling for Linux `.rpm` | ✅ | -| Package tooling for Windows `.msi` | ✅ | -| Manage/update osquery extensions | ✅ | -| Manage cgroups for Linux performance | 🔜 | - -## Usage - -General information and flag documentation can be accessed by running `orbit --help`. - -### Permissions - -Orbit generally expects root permissions to be able to create and access its working files. - -To get root level permissions: - -#### macOS/Linux - -Prefix `orbit` commands with `sudo` (`sudo orbit ...`) or run in a root shell. - -#### Windows - -Run Powershell or cmd.exe with "Run as administrator" and start `orbit` commands from that shell. - -### Osquery shell - -Run an `osqueryi` shell with `orbit osqueryi` or `orbit shell`. - -### Connect to a Fleet server - -Use the `--fleet-url` and `--enroll-secret` flags to connect to a Fleet server. - -For example: - -```sh -orbit --fleet-url=https://localhost:8080 --enroll-secret=the_secret_value -``` - -Use `--fleet_certificate` to provide a path to a certificate bundle when necessary for osquery to verify the authenticity of the Fleet server (typically when using a Windows client or self-signed certificates): - -```sh -orbit --fleet-url=https://localhost:8080 --enroll-secret=the_secret_value --fleet-certificate=cert.pem -``` - -Add the `--insecure` flag for connections using otherwise invalid certificates: - -```sh -orbit --fleet-url=https://localhost:8080 --enroll-secret=the_secret_value --insecure -``` - -### Osquery flags - -Orbit can be used as a near drop-in replacement for `osqueryd`, enhancing standard osquery with autoupdate capabilities. Orbit passes through any options after `--` directly to the `osqueryd` instance. - -For example, the following would be a typical drop-in usage of Orbit: - -```sh -orbit -- --flagfile=flags.txt -``` - -### Osquery extensions - -Orbit can be used to remotely deploy and manage osquery extensions. This saves the time and energy required to maintain extensions using a separate tool like Munki or an MDM solution. - -[Learn how](https://fleetdm.com/docs/using-fleet/configuration-files#code-extensions-code-option) - -## Packaging - -Orbit, like standalone osquery, is typically deployed via OS-specific packages. Tooling is provided with this repository to generate installation packages. - -### Dependencies - -Orbit currently supports building packages on macOS and Linux. - -Before building packages, clone or download this repository and [install Go](https://golang.org/doc/install). - -Building Windows packages requires Docker to be installed. - -### Packaging support - -- **macOS** - `.pkg` package generation with (optional) [notarization](https://developer.apple.com/documentation/xcode/notarizing_macos_software_before_distribution) and codesigning - Persistence via `launchd`. - -- **Linux** - `.deb` (Debian, Ubuntu, etc.) & `.rpm` (RHEL, CentOS, etc.) package generation - Persistence via `systemd`. - -- **Windows** - `.msi` package generation - Persistence via Services. - -### Building packages - -Use `fleetctl package` to run the packaging tools. - -The only required parameter is `--type`, use one of `deb`, `rpm`, `pkg`, or `msi`. - -Configure osquery to connect to a Fleet (or other TLS) server with the `--fleet-url` and `--enroll-secret` flags. - -A minimal invocation for communicating with Fleet: - -```sh -fleetctl package --type deb --fleet-url=fleet.example.com --enroll-secret=notsosecret -``` - -This will build a `.deb` package configured to communicate with a Fleet server at `fleet.example.com` using the enroll secret `notsosecret`. - -When the Fleet server uses a self-signed (or otherwise invalid) TLS certificate, package with the `--insecure` or `--fleet-certificate` options. - -#### Configuration options - -The following command-line flags allow you to configure an osquery installer further to communicate with a specific Fleet instance. - -| Flag | Options | -| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -| --type | **Required** - Type of package to build.
Options: `pkg`(macOS),`msi`(Windows), `deb`(Debian based Linux), `rpm`(RHEL, CentOS, etc.) | -| --fleet-desktop | Include Fleet Desktop. | -| --enroll-secret | Enroll secret for authenticating to Fleet server | -| --fleet-url | URL (`host:port`) of Fleet server | -| --fleet-certificate | Path to server certificate bundle | -| --identifier | Identifier for package product (default: `com.fleetdm.orbit`) | -| --version | Version for package product (default: `0.0.3`) | -| --insecure | Disable TLS certificate verification (default: `false`) | -| --service | Install osquery with a persistence service (launchd, systemd, etc.) (default: `true`) | -| --sign-identity | Identity to use for macOS codesigning | -| --notarize | Whether to notarize macOS packages (default: `false`) | -| --disable-updates | Disable auto updates on the generated package (default: false) | -| --osqueryd-channel | Update channel of osqueryd to use (default: `stable`) | -| --orbit-channel | Update channel of Orbit to use (default: `stable`) | -| --desktop-channel | Update channel of desktop to use (default: `stable`) | -| --update-url | URL for update server (default: `https://tuf.fleetctl.com`) | -| --update-roots | Root key JSON metadata for update server (from fleetctl updates roots) | -| --use-system-configuration | Try to read --fleet-url and --enroll-secret using configuration in the host (currently only macOS profiles are supported) | -| --debug | Enable debug logging (default: `false`) | -| --verbose | Log detailed information when building the package (default: false) | -| --help, -h | show help (default: `false`) | - -#### Fleet Desktop - -[Fleet Desktop](./Fleet-desktop.md) is a menu bar icon available on macOS, Windows, and Linux that gives your end users visibility into the security posture of their machine. - -You can include Fleet Desktop in the orbit package by including the `--fleet-desktop`option. - -#### Update channels - -Orbit uses the concept of "update channels" to determine the version of Orbit, Fleet Desktop, osquery, and any extensions (extension support coming soon) to run. This concept is modeled from the common versioning convention for Docker containers. - -Configure update channels for Orbit and osqueryd with the `--orbit-channel`, `--desktop-channel` and `--osqueryd-channel` flags when packaging. - -| Channel | Versions | -| ------- | -------- | -| `4` | 4.x.x | -| `4.6` | 4.6.x | -| `4.6.0` | 4.6.0 | - -Additionally, `stable` and `edge` are special channel names. The `stable` channel will provide the most recent osquery version that Fleet deems to be stable. When a new version of osquery is released, it's added to the `edge` channel for beta testing. Fleet then provides input to the osquery TSC based on testing. After the version is declared stable by the osquery TSC, Fleet will promote the version to `stable` ASAP. - -#### macOS signing & notarization - -Orbit's packager can automate the codesigning and notarization steps to allow the resulting package to generate packages that appear "trusted" when installed on macOS hosts. Signing and notarization are supported only on macOS hosts. - -For signing, a "Developer ID Installer" certificate must be available on the build machine ([generation instructions](https://help.apple.com/xcode/mac/current/#/dev154b28f09)). Use `security find-identity -v` to verify the existence of this certificate and make note of the identifier provided in the left column. - -For notarization, valid App Store Connect credentials must be available on the build machine. Set these in the environment variables `AC_USERNAME` and `AC_PASSWORD`. It's common to configure this via [app-specific passwords](https://support.apple.com/en-ca/HT204397). Some organizations (notably those with Apple Enterprise Developer Accounts) may also need to specify `AC_TEAM_ID`. This value can be found on the [Apple Developer "Membership" page](https://developer.apple.com/account/#!/membership) under "Team ID." - -Build a signed and notarized macOS package with an invocation like the following: - -```sh -AC_USERNAME=zach@example.com AC_PASSWORD=llpk-sije-kjlz-jdzw fleetctl package --type=pkg --fleet-url=fleet.example.com --enroll-secret=63SBzTT+2UyW --sign-identity 3D7260BF99539C6E80A94835A8921A988F4E6498 --notarize -``` - -This process may take several minutes, as the notarization process completes on Apple's servers. - -After successful notarization, the generated "ticket" is automatically stapled to the package. - -#### Orbit osquery result and status logs - -If the `logger_path` configuration is set to `filesystem`, Orbit will store osquery's "result" and -"status" logs to the following directories: - - Windows: C:\Program Files\Orbit\osquery_log - - macOS: /opt/orbit/osquery_log - - Linux: /opt/orbit/osquery_log - -#### Orbit mTLS support - -Orbit supports using TLS client certificates for authentication to the Fleet server and [TUF](https://theupdateframework.io/) server. -This functionality is licensed under the Fleet EE License. Usage requires a current Fleet EE subscription. - -> The mTLS feature requires Orbit to be version v1.10.0 or greater and `fleetctl` v4.31.0 or greater. - -When generating the packages, use the following flags: -```sh -fleetctl package \ - [...] - --fleet-tls-client-certificate=fleet-client.crt \ - --fleet-tls-client-key=fleet-client.key \ - --update-tls-client-certificate=update-client.crt \ - --update-tls-client-key=update-client.key \ - [...] -``` -The certificates must be in PEM format. - -The client certificates can also be pushed to existing installations by placing them in the following locations: -- For macOS and Linux: - - `/opt/orbit/fleet_client.crt` - - `/opt/orbit/fleet_client.key` - - `/opt/orbit/update_client.crt` - - `/opt/orbit/update_client.key` -- For Windows: - - `C:\Program Files\Orbit\fleet_client.crt` - - `C:\Program Files\Orbit\fleet_client.key` - - `C:\Program Files\Orbit\update_client.crt` - - `C:\Program Files\Orbit\update_client.key` - -If using Fleet Desktop, you may need to specify an alternative host for the "My device" URL (in the Fleet tray icon). -Such alternative host should not require client certificates on the TLS connection. -```sh -fleetctl package - [...] - --fleet-desktop \ - --fleet-desktop-alternative-browser-host=fleet-desktop.example.com \ - [...] -``` -If this setting is not used, you will need to configure client TLS certificates on devices' browsers. - -#### Orbit development - -##### Run Orbit from source - -To execute orbit from source directly, run the following command: - -```sh -go run github.com/fleetdm/fleet/v4/orbit/cmd/orbit \ - --dev-mode \ - --disable-updates \ - --root-dir /tmp/orbit \ - --fleet-url https://localhost:8080 \ - --insecure \ - --enroll-secret Pz3zC0NMDdZfb3FtqiLgwoexItojrYh/ \ - -- --verbose -``` - -Or, using a `flagfile.txt` for osqueryd: -```sh -go run github.com/fleetdm/fleet/v4/orbit/cmd/orbit \ - --dev-mode \ - --disable-updates \ - --root-dir /tmp/orbit \ - -- --flagfile=flagfile.txt --verbose -``` - -##### Generate installer packages from Orbit source - -The `fleetctl package` command generates installers by fetching the targets/executables from a [TUF](https://theupdateframework.io/) repository. -To generate an installer that contains an Orbit built from source, you need to setup a local TUF repository. -The following document explains how you can generate a TUF repository and installers that use it: [tools/tuf/test](https://github.com/fleetdm/fleet/tree/main/tools/tuf/test/README.md). - -### Troubleshooting - -#### Logs - -Orbit captures and streams osqueryd's stdout/stderr into its own stdout/stderr output. -These are the log destinations for each platform: -- Linux: Orbit and osqueryd stdout/stderr output is sent to syslog (`/var/log/syslog` on Debian systems and `/var/log/messages` on CentOS). -- macOS: `/private/var/log/orbit/orbit.std{out|err}.log`. -- Windows: `C:\Windows\system32\config\systemprofile\AppData\Local\FleetDM\Orbit\Logs\orbit-osquery.log` (the log file is rotated). - Users will need administrative permissions on the host to access these log destinations. -#### Debug - -You can use the `--debug` option in `fleetctl package` to generate installers in "debug mode." This mode increases the verbosity of logging for orbit and osqueryd (log DEBUG level). - -### Uninstall - -#### Windows - -Use the "Add or remove programs" dialog to remove Orbit. - -#### Linux - -Uninstall the package with the corresponding package manager: - -- Ubuntu -```sh -sudo apt remove fleet-osquery -y -``` -- CentOS -```sh -sudo rpm -e fleet-osquery-X.Y.Z.x86_64 -``` - -#### macOS - -Run the [cleanup script](https://github.com/fleetdm/fleet/tree/main/orbit/tools/cleanup/cleanup_macos.sh). - -## Bugs - -[Create an issue](https://github.com/fleetdm/fleet/issues) to report a bug or request a feature. - - diff --git a/docs/Using-Fleet/Permissions.md b/docs/Using-Fleet/Permissions.md deleted file mode 100644 index 8a6d2d723..000000000 --- a/docs/Using-Fleet/Permissions.md +++ /dev/null @@ -1,157 +0,0 @@ -# Permissions - -Users have different abilities depending on the access level they have. - -## Roles - -### Admin - -Users with the admin role receive all permissions. - -### Maintainer - -Maintainers can manage most entities in Fleet, like queries, policies, labels and schedules. -Unlike admins, maintainers cannot edit higher level settings like application configuration, teams or users. - -### Observer - -The Observer role is a read-only role. It can access most entities in Fleet, like queries, policies, labels, schedules, application configuration, teams, etc. -They can also run queries configured with the `observer_can_run` flag set to `true`. - -### Observer+ - -`Applies only to Fleet Premium` - -Observer+ is an Observer with the added ability to run *any* query. - -### GitOps - -`Applies only to Fleet Premium` - -GitOps is a modern approach to Continuous Deployment (CD) that uses Git as the single source of truth for declarative infrastructure and application configurations. -GitOps is an API-only and write-only role that can be used on CI/CD pipelines. - -## User permissions - -| **Action** | Observer | Observer+* | Maintainer | Admin | GitOps* | -| ------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ---------- | ---------- | ----- | ------- | -| View all [activity](https://fleetdm.com/docs/using-fleet/rest-api#activities) | ✅ | ✅ | ✅ | ✅ | | -| View all hosts | ✅ | ✅ | ✅ | ✅ | | -| Filter hosts using [labels](https://fleetdm.com/docs/using-fleet/rest-api#labels) | ✅ | ✅ | ✅ | ✅ | | -| Target hosts using labels | ✅ | ✅ | ✅ | ✅ | | -| Add and delete hosts | | | ✅ | ✅ | | -| Transfer hosts between teams\* | | | ✅ | ✅ | ✅ | -| Create, edit, and delete labels | | | ✅ | ✅ | ✅ | -| View all software | ✅ | ✅ | ✅ | ✅ | | -| Filter software by [vulnerabilities](https://fleetdm.com/docs/using-fleet/vulnerability-processing#vulnerability-processing) | ✅ | ✅ | ✅ | ✅ | | -| Filter hosts by software | ✅ | ✅ | ✅ | ✅ | | -| Filter software by team\* | ✅ | ✅ | ✅ | ✅ | | -| Manage [vulnerability automations](https://fleetdm.com/docs/using-fleet/automations#vulnerability-automations) | | | | ✅ | ✅ | -| Run queries designated "**observer can run**" as live queries against all hosts | ✅ | ✅ | ✅ | ✅ | | -| Run any query as [live query](https://fleetdm.com/docs/using-fleet/fleet-ui#run-a-query) against all hosts | | ✅ | ✅ | ✅ | | -| Create, edit, and delete queries | | | ✅ | ✅ | ✅ | -| View all queries\** | ✅ | ✅ | ✅ | ✅ | | -| Add, edit, and remove queries from all schedules | | | ✅ | ✅ | ✅ | -| Create, edit, view, and delete packs | | | ✅ | ✅ | ✅ | -| View all policies | ✅ | ✅ | ✅ | ✅ | | -| Filter hosts using policies | ✅ | ✅ | ✅ | ✅ | | -| Create, edit, and delete policies for all hosts | | | ✅ | ✅ | ✅ | -| Create, edit, and delete policies for all hosts assigned to team\* | | | ✅ | ✅ | ✅ | -| Manage [policy automations](https://fleetdm.com/docs/using-fleet/automations#policy-automations) | | | | ✅ | ✅ | -| Create, edit, view, and delete users | | | | ✅ | | -| Add and remove team members\* | | | | ✅ | ✅ | -| Create, edit, and delete teams\* | | | | ✅ | ✅ | -| Create, edit, and delete [enroll secrets](https://fleetdm.com/docs/deploying/faq#when-do-i-need-to-deploy-a-new-enroll-secret-to-my-hosts) | | | ✅ | ✅ | ✅ | -| Create, edit, and delete [enroll secrets for teams](https://fleetdm.com/docs/using-fleet/rest-api#get-enroll-secrets-for-a-team)\* | | | ✅ | ✅ | | -| Read organization settings\*** | ✅ | ✅ | ✅ | ✅ | | -| Read Single Sign-On settings\*** | | | | ✅ | | -| Read SMTP settings\*** | | | | ✅ | | -| Read osquery agent options\*** | | | | ✅ | | -| Edit [organization settings](https://fleetdm.com/docs/using-fleet/configuration-files#organization-settings) | | | | ✅ | ✅ | -| Edit [agent options](https://fleetdm.com/docs/using-fleet/configuration-files#agent-options) | | | | ✅ | ✅ | -| Edit [agent options for hosts assigned to teams](https://fleetdm.com/docs/using-fleet/configuration-files#team-agent-options)\* | | | | ✅ | ✅ | -| Initiate [file carving](https://fleetdm.com/docs/using-fleet/rest-api#file-carving) | | | ✅ | ✅ | | -| Retrieve contents from file carving | | | | ✅ | | -| View Apple mobile device management (MDM) certificate information | | | | ✅ | | -| View Apple business manager (BM) information | | | | ✅ | | -| Generate Apple mobile device management (MDM) certificate signing request (CSR) | | | | ✅ | | -| View disk encryption key for macOS hosts | ✅ | ✅ | ✅ | ✅ | | -| Create edit and delete configuration profiles for macOS hosts | | | ✅ | ✅ | ✅ | -| Execute MDM commands on macOS hosts*** | | | ✅ | ✅ | | -| View results of MDM commands executed on macOS hosts*** | ✅ | ✅ | ✅ | ✅ | | -| Edit [MDM settings](https://fleetdm.com/docs/using-fleet/mdm-macos-settings) | | | | ✅ | ✅ | -| Edit [MDM settings for teams](https://fleetdm.com/docs/using-fleet/mdm-macos-settings) | | | | ✅ | ✅ | -| Upload an EULA file for MDM automatic enrollment\* | | | | ✅ | | -| View/download MDM macOS setup assistant\* | | | ✅ | ✅ | | -| Edit/upload MDM macOS setup assistant\* | | | ✅ | ✅ | ✅ | -| View metadata of MDM macOS bootstrap packages\* | | | ✅ | ✅ | | -| Edit/upload MDM macOS bootstrap packages\* | | | ✅ | ✅ | ✅ | -| Enable/disable MDM macOS setup end user authentication\* | | | ✅ | ✅ | ✅ | - -\* Applies only to Fleet Premium - -\** Global observers can view all queries but the UI and fleetctl only list the ones they can run (**observer can run**). - -\*** Applies only to [Fleet REST API](https://fleetdm.com/docs/using-fleet/rest-api) - -## Team member permissions - -`Applies only to Fleet Premium` - -Users in Fleet either have team access or global access. - -Users with team access only have access to the [hosts](https://fleetdm.com/docs/using-fleet/rest-api#hosts), [software](https://fleetdm.com/docs/using-fleet/rest-api#software), [schedules](https://fleetdm.com/docs/using-fleet/fleet-ui#schedule-a-query) , and [policies](https://fleetdm.com/docs/using-fleet/rest-api#policies) assigned to -their team. - -Users with global access have access to all -[hosts](https://fleetdm.com/docs/using-fleet/rest-api#hosts), [software](https://fleetdm.com/docs/using-fleet/rest-api#software), [queries](https://fleetdm.com/docs/using-fleet/rest-api#queries), [schedules](https://fleetdm.com/docs/using-fleet/fleet-ui#schedule-a-query) , and [policies](https://fleetdm.com/docs/using-fleet/rest-api#policies). Check out [the user permissions -table](#user-permissions) above for global user permissions. - -Users can be a member of multiple teams in Fleet. - -Users that are members of multiple teams can be assigned different roles for each team. For example, a user can be given access to the "Workstations" team and assigned the "Observer" role. This same user can be given access to the "Servers" team and assigned the "Maintainer" role. - -| **Action** | Team observer | Team observer+ | Team maintainer | Team admin | Team GitOps | -| -------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------------- | --------------- | ---------- | ----------- | -| View hosts | ✅ | ✅ | ✅ | ✅ | | -| Filter hosts using [labels](https://fleetdm.com/docs/using-fleet/rest-api#labels) | ✅ | ✅ | ✅ | ✅ | | -| Target hosts using labels | ✅ | ✅ | ✅ | ✅ | | -| Add and delete hosts | | | ✅ | ✅ | | -| Filter software by [vulnerabilities](https://fleetdm.com/docs/using-fleet/vulnerability-processing#vulnerability-processing) | ✅ | ✅ | ✅ | ✅ | | -| Filter hosts by software | ✅ | ✅ | ✅ | ✅ | | -| Filter software | ✅ | ✅ | ✅ | ✅ | | -| Run queries designated "**observer can run**" as live queries against hosts | ✅ | ✅ | ✅ | ✅ | | -| Run any query as [live query](https://fleetdm.com/docs/using-fleet/fleet-ui#run-a-query) | | ✅ | ✅ | ✅ | | -| Create, edit, and delete only **self authored** queries | | | ✅ | ✅ | ✅ | -| View all queries\** | ✅ | ✅ | ✅ | ✅ | | -| Add, edit, and remove queries from the schedule | | | ✅ | ✅ | ✅ | -| View policies | ✅ | ✅ | ✅ | ✅ | | -| View global (inherited) policies | ✅ | ✅ | ✅ | ✅ | | -| Run global (inherited) policies as a live policy | | | ✅ | ✅ | | -| Filter hosts using policies | ✅ | ✅ | ✅ | ✅ | | -| Create, edit, and delete team policies | | | ✅ | ✅ | ✅ | -| Manage [policy automations](https://fleetdm.com/docs/using-fleet/automations#policy-automations) | | | | ✅ | ✅ | -| Add and remove team members | | | | ✅ | ✅ | -| Edit team name | | | | ✅ | ✅ | -| Create, edit, and delete [team enroll secrets](https://fleetdm.com/docs/using-fleet/rest-api#get-enroll-secrets-for-a-team) | | | ✅ | ✅ | | -| Read organization settings\* | ✅ | ✅ | ✅ | ✅ | | -| Read agent options\* | ✅ | ✅ | ✅ | ✅ | | -| Edit [agent options](https://fleetdm.com/docs/using-fleet/configuration-files#agent-options) | | | | ✅ | ✅ | -| Initiate [file carving](https://fleetdm.com/docs/using-fleet/rest-api#file-carving) | | | ✅ | ✅ | | -| View disk encryption key for macOS hosts | ✅ | ✅ | ✅ | ✅ | | -| Create edit and delete configuration profiles for macOS hosts | | | ✅ | ✅ | ✅ | -| Execute MDM commands on macOS hosts, and read command results* | | | ✅ | ✅ | | -| Execute MDM commands on macOS hosts* | | | ✅ | ✅ | | -| View results of MDM commands executed on macOS hosts* | ✅ | ✅ | ✅ | ✅ | | -| Edit [team MDM settings](https://fleetdm.com/docs/using-fleet/mdm-macos-settings) | | | | ✅ | ✅ | -| View/download MDM macOS setup assistant | | | ✅ | ✅ | | -| Edit/upload MDM macOS setup assistant | | | ✅ | ✅ | ✅ | -| View metadata of MDM macOS bootstrap packages | | | ✅ | ✅ | | -| Edit/upload MDM macOS bootstrap packages | | | ✅ | ✅ | ✅ | -| Enable/disable MDM macOS setup end user authentication | | | ✅ | ✅ | ✅ | - -\* Applies only to [Fleet REST API](https://fleetdm.com/docs/using-fleet/rest-api) - -\** Team observers can view all queries but the UI and fleetctl only list the ones they can run (**observer can run**). - - diff --git a/docs/Using-Fleet/Process-File-Events.md b/docs/Using-Fleet/Process-File-Events.md deleted file mode 100644 index 086c6d2aa..000000000 --- a/docs/Using-Fleet/Process-File-Events.md +++ /dev/null @@ -1,179 +0,0 @@ -# Querying process_file_events on CentOS 7 - -This guide contains step-by-step instructions for configuring the `process_file_events` table on CentOS 7. - -## Setup a CentOS 7 VM - -Setup a CentOS 7 VM. (VMWare Fusion was used for this guide.) -The following kernel release was used: -```sh -$ uname --kernel-release -3.10.0-1160.83.1.el7.x86_64 -``` - -> All commands shown in this guide were executed as `root`. - -## Disable auditd - -The `process_file_events` table will not work if the `auditd` daemon is running (there can only be one audit daemon). -To disable auditd run the following: -```sh -systemctl disable auditd -systemctl stop auditd - -# Make sure auditd is not running by executing the following: -ps -Af | grep auditd -``` - -If auditd is running, osquery will log the following error: -```log -I0613 11:25:39.959703 29626 auditdnetlink.cpp:686] Failed to set the netlink owner -``` - -## Create test files - -> The `process_file_events` table can only process events for files that existed before the osquery initialization. -> New files created after osqueryd has initialized won't be tracked by the `process_file_events` table. - -Create the following test files in the CentOS VM: -```sh -mkdir /etc/foobar -echo "zoo" > /etc/foobar/zoo.txt -echo "other" > /etc/foobar/other.txt -``` - -## Create a test team in Fleet. - -We will use a test team with special settings to avoid impacting other hosts. - -## Install fleetd on the CentOS instance and enroll host - -Generate fleetd rpm package (This step was executed on macOS.) -```sh -fleetctl package --type=rpm --fleet-desktop --fleet-url=https://host.docker.internal:8080 --enroll-secret=[redacted team enroll secret] --insecure --debug -``` - -Install fleetd package on the CentOS 7 VM: -```sh -rpm --install fleet-osquery-1.10.0.x86_64.rpm -``` - -## Set team agent options - -Configure following settings on the team's agent options: -```sh -config: - options: - pack_delimiter: / - logger_tls_period: 10 - distributed_plugin: tls - disable_distributed: false - logger_tls_endpoint: /api/osquery/log - distributed_interval: 10 - distributed_tls_max_attempts: 3 - decorators: - load: - - SELECT uuid AS host_uuid FROM system_info; - - SELECT hostname AS hostname FROM system_info; - file_paths: - etc: - - /etc/foobar/%% -command_line_flags: - verbose: true - events_expiry: 3600 - disable_events: false - disable_audit: false - audit_persist: true - audit_allow_fim_events: true - audit_allow_config: true - audit_backlog_limit: 60000 - audit_allow_process_events: false - audit_allow_sockets: false - audit_allow_user_events: false - audit_allow_selinux_events: false - audit_allow_kill_process_events: false - audit_allow_apparmor_events: false - audit_allow_seccomp_events: false - enable_bpf_events: false -``` - -Check osquery `command_line_flags` were delivered successfully to the agent: -```sh -sudo cat /opt/orbit/osquery.flags ---audit_allow_apparmor_events=false ---enable_bpf_events=false ---audit_allow_config=true ---audit_backlog_limit=60000 ---audit_allow_user_events=false ---audit_allow_seccomp_events=false ---audit_allow_selinux_events=false ---audit_allow_sockets=false ---audit_allow_process_events=false ---audit_persist=true ---audit_allow_fim_events=true ---audit_allow_kill_process_events=false ---disable_audit=false ---verbose=true ---events_expiry=3600 ---disable_events=false -``` - -### About the flags - -- `file_paths:` We set `/etc/foobar/%%` as the path to monitor for file changes. -- `verbose: true`: We set this to `true` for troubleshooting purposes only. -- `disable_events: false`: Must be set to `false` to enable evented tables in general. -- `events_expiry: 3600`: The `events_expiry` value is the time it takes for events to be cleared from osquery local storage. -- `disable_audit: false`: Must be set to `false` to enable the audit events. -- `audit_persist: true`: Set to `true` to attempt to retain control of audit. -- `audit_allow_fim_events: true`: Must be set to `true` to generate FIM events (otherwise the `process_file_events` will generate no events). Once this is set correctly, the user should see "Enabling audit rules for the process_file_events table" in the logs. -- `audit_allow_config: true`: Must be set to `true` to allow osquery to configure the audit service (basically set backlog limit and wait time below). -- `audit_backlog_limit: 60000`: Sets the queue length for audit events awaiting transfer to osquery audit subscriber. We set this to a high value first to make sure the table is working, then it should be modified to a better value suited for production. -- The following flags were set to `false` to avoid unnecessary load on the host: `audit_allow_process_events: false`, `audit_allow_sockets: false`, `audit_allow_user_events: false`, `audit_allow_selinux_events: false`, `audit_allow_kill_process_events: false`, `audit_allow_apparmor_events: false`, `audit_allow_seccomp_events: false`, `enable_bpf_events: false`. - -## Make sure osquery audit subscriber is working - -```sh -auditctl -s - -enabled 1 -failure 0 -pid 21590 -rate_limit 0 -backlog_limit 60000 -lost 1137311 -backlog 991 -loginuid_immutable 0 unlocked -``` - -`enabled` should be `1` and `pid`'s value should be the process ID of osquery. - -## Modify the test files - -```sh -echo "boo" >> /etc/foobar/zoo.txt -rm /etc/foobar/other.txt -``` - -> Remember: the files must exist before the osquery process is initialized. -> Creating or modifying new files won't generate `process_file_events` events. - -## Query the process_file_events table - -Run the following live query: -```sql -SELECT * from process_file_events; -``` - -It should return two events, one with `operation=write` and one with `operation=unlink`. - -## Additional notes - -Make sure to keep an eye on logs like the following: -```log -auditdnetlink.cpp:354 The Audit publisher has throttled reading records from Netlink for 0.2 seconds. Some events may have been lost. -``` -Some events might get lost due to system load or low CPU/memory resources. - - - \ No newline at end of file diff --git a/docs/Using-Fleet/README.md b/docs/Using-Fleet/README.md deleted file mode 100644 index 902922a88..000000000 --- a/docs/Using-Fleet/README.md +++ /dev/null @@ -1,28 +0,0 @@ -# Using Fleet - -### [Fleet UI](./Fleet-UI.md) -Provides documentation about running and scheduling queries from within the Fleet UI - -### [fleetctl CLI](./fleetctl-CLI.md) -Includes resources for setting up and configuring Fleet via the fleetctl CLI - -### [REST API](./REST-API.md) -Provides resources for working with Fleet's API and includes example code for endpoints - -### [Adding hosts](./Adding-hosts.md) -Provides resources for enrolling your hosts to Fleet - -### [Log destinations](./Log-destinations.md) -Includes documentation on the log destinations for sending with osquery logs - -### [Osquery processes](./Osquery-process.md) -Includes documentation about osquery children processes and under which conditions they are terminated - -### [Monitoring Fleet](./Monitoring-Fleet.md) -Provides documentation for load balancer health checks and working with Fleet server metrics and performance - -### [Application Security](./Application-Security.md) -Includes information on how Fleet mitigates against the OWASP top 10 issues - -### [FAQ](./FAQ.md) -Includes frequently asked questions and answers about using Fleet from the Fleet community diff --git a/docs/Using-Fleet/REST-API.md b/docs/Using-Fleet/REST-API.md deleted file mode 100644 index 938d15f6c..000000000 --- a/docs/Using-Fleet/REST-API.md +++ /dev/null @@ -1,7565 +0,0 @@ -# REST API - -- [Authentication](#authentication) -- [Activities](#activities) -- [Fleet configuration](#fleet-configuration) -- [File carving](#file-carving) -- [Hosts](#hosts) -- [Labels](#labels) -- [Mobile device management (MDM)](#mobile-device-management-mdm) -- [Policies](#policies) -- [Queries](#queries) -- [Schedule](#schedule) -- [Sessions](#sessions) -- [Software](#software) -- [Targets](#targets) -- [Teams](#teams) -- [Translator](#translator) -- [Users](#users) -- [API errors](#api-responses) - -Use the Fleet APIs to automate Fleet. - -This page includes a list of available resources and their API routes. - -## Authentication - -- [Retrieve your API token](#retrieve-your-api-token) -- [Log in](#log-in) -- [Log out](#log-out) -- [Forgot password](#forgot-password) -- [Change password](#change-password) -- [Reset password](#reset-password) -- [Me](#me) -- [SSO config](#sso-config) -- [Initiate SSO](#initiate-sso) -- [SSO callback](#sso-callback) - -### Retrieve your API token - -All API requests to the Fleet server require API token authentication unless noted in the documentation. API tokens are tied to your Fleet user account. - -To get an API token, retrieve it from the "Account settings" > "Get API token" in the Fleet UI (`/profile`). Or, you can send a request to the [login API endpoint](#log-in) to get your token. - -Then, use that API token to authenticate all subsequent API requests by sending it in the "Authorization" request header, prefixed with "Bearer ": - -``` -Authorization: Bearer
-
-
-
-Vulnerable software can have one or more vulnerabilities (CVEs).
-
-For Fleet Premium users, each CVE includes its CVSS base score (reported by the [National Vulnerability Database](https://nvd.nist.gov/)), probability of exploit (reported by [FIRST](https://www.first.org/epss/)), and whether or not there is a known exploit in the wild (reported by the [Cybersecurity & Infrastructure Security Agency](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)).
-
-Fleet's strategy for detecting vulnerabilities (CVEs) varies according to the host's platform and
-the software in question. For macOS and Windows hosts, in general,
-CVEs are detected using the National Vulnerability Database (NVD) except for MacOffice applications,
-for which we use the release notes published by Microsoft. For Linux hosts,
-CVEs are detected using the official OVAL definitions maintained by the different publishers (Canonical, Red Hat etc.).
-
-### Windows/MacOS hosts using the NVD dataset
-
-First, Fleet retrieves the installed software for each host using osquery queries. Then, Fleet
-translates each installed software into [Common Platform Enumeration (CPE)](https://en.wikipedia.org/wiki/Common_Platform_Enumeration) names.
-
-Then, using the CPEs, Fleet searches the list of [Common Vulnerabilities and Exposure
-(CVE)](https://en.wikipedia.org/wiki/Common_Vulnerabilities_and_Exposures) identifiers listed in the NVD
-to detect the CVEs that match the defined CPEs.
-
-If matches are found, they are exposed on each host's
-**Host details** page and on the **Home** page in the Fleet UI. The CVEs are also exposed in the
-`fleetctl get software` command and the `GET api/v1/fleet/hosts/{id}` and `GET
-api/v1/fleet/software` API routes.
-
-Vulnerability processing happens on the Fleet instance and not on the host machine. Because of this,
-detected vulnerabilities cannot be used in the same way you would use an osquery query (e.g. you wouldn't
-be able write a query to retrieve all CVEs).
-
-### MacOffice release notes
-We periodically parse the Mac Office release notes posted at
-https://learn.microsoft.com/en-us/officeupdates/release-notes-office-for-mac and for each release
-note we extract the version
-information and what vulnerabilities were patched with the release, we then examine all installed
-macOS apps and if an Office app is found we compare its version with the release notes metadata
-and report back any vulnerabilities to which the software is susceptible.
-
-### Linux hosts
-
-First, we determine what Linux distributions are part of your fleet (keep in mind that there will
-be a small delay between the time a new Linux hosts is added and the time the host is 'detected'). We then
-use
-that information to determine what OVAL definitions need to be downloaded and parsed - you can find
-a list of all the OVAL definitions we use
-[here](https://github.com/fleetdm/nvd/blob/master/oval_sources.json). OVAL definitions will be
-refreshed on a daily basis.
-
-Finally, we look at the software inventory of each host and execute the assertions contained in the
-corresponding OVAL file - any match is reported using the same channels as with Windows/Mac OS vulnerabilities
-
-## Coverage
-
-For Windows/Mac OS Fleet attempts to detect vulnerabilities for installed software that falls into the following categories (types):
-
-### Apps
-- macOS
-- Windows
-
-### Browser plugins
-- macOS, Windows
- - Chrome extensions
- - Firefox extensions
-
-### Packages
-- macOS
- - Python
- - Packages installed using Homebrew
-
-- Windows
- - Python
- - Atom
- - Packages installed using Chocolatey
-
-For Linux, we adhere to whatever is defined in the OVAL definitions, except for:
-- Kernel vulnerabilities.
-- Vulnerabilities involving configuration files.
-
-As of right now, the following distributions are supported:
-- Ubuntu
-- RHEL based distros (Red Hat, CentOS, Fedora, and Amazon Linux)
-
-As of right now, only app names with all ASCII characters are supported. Apps with names featuring non-ASCII characters, such as Cyrillic, will not generate matches.
-
-The ingestion of software varies per platform. For each platform, we run an [osquery query](#ingesting-software-lists-from-hosts) to ingest software.
-
-## Configuration
-
-When upgrading to Fleet 4.7.0 or later, vulnerability processing is automatically enabled if
-vulnerability processing and software inventory are not explicitly disabled.
-
-If you explicitly disabled vulnerability processing, and now would like to enable this feature, first enable the software inventory feature by setting the following app config:
-
-```
----
-apiVersion: v1
-kind: config
-spec:
- features:
- enable_software_inventory: true
-```
-
-Then, enable vulnerability processing by specifying a path where Fleet will download the different
-data feeds. This can be done by setting the following app config:
-
-```
----
-apiVersion: v1
-kind: config
-spec:
- vulnerabilities:
- databases_path: /some/path
-```
-
-Or through environment variables:
-
-```
-FLEET_VULNERABILITIES_DATABASES_PATH=/some/path
-```
-
-The path specified needs to exist and Fleet needs to be able to read and write to and from it. This is the only mandatory
-configuration needed for vulnerability processing to work. Additional options, like vulnerability check frequency, can be
-found in the [configuration documentation](https://fleetdm.com/docs/deploying/configuration#vulnerabilities).
-
-You'll need to restart the Fleet instances after changing these settings.
-
-### Advanced Configuration
-
-Fleet runs vulnerability downloading and processing via internal scheduled cron job. This internal mechanism is very useful
-for frictionless deployments and is well suited for most use cases. However, in larger deployments,
-where there can be dozens of Fleet server replicas sitting behind a load balancer, it is desirable to manage vulnerability processing externally.
-
-The reasons for this are as follows:
-
-- lower resource requirements across the entire Fleet server deployment (as vulnerability processing requires considerably more resources than just running Fleet server alone)
-- more control over scheduling constraints (only process during windows of low utilization, etc.)
-
-It is possible to limit vulnerability processing to a single [dedicated host](https://fleetdm.com/docs/deploying/configuration#current-instance-checks), by setting
-`current_instance_checks` to `no` but still run one Fleet server as `yes`, but the drawback here is still having to dedicate resources
-for this single host 24/7. The Fleet binary has a command which handles the same vulnerability processing, but will exit (successfully with 0) on completion. Using this sub-command we can delegate vulnerability processing
-to external systems such as:
-
-- [ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/scheduling_tasks.html)
-- [K8S](https://kubernetes.io/docs/tasks/job/automated-tasks-with-cron-jobs/)
-- [GCP](https://cloud.google.com/run/docs/triggering/using-scheduler#create_job)
-- [Plain old cron](https://en.wikipedia.org/wiki/Cron)
-
-To opt into this functionality, be sure to configure your Fleet server deployment with
-```
-FLEET_VULNERABILITIES_DISABLE_SCHEDULE=true
-```
-which will **disable** the internal scheduling mechanism for vulnerability processing.
-
-And then externally run with the same environment variables/configuration files passed to the server command.
-```
-fleet vuln_processing
-```
-
-## Performance
-
-### Windows/Mac OS
-
-Vulnerability processing is performed in one Fleet instance. If your Fleet deployment uses multiple
-instances, only one will be doing the work.
-
-In order to conduct vulnerability processing, Fleet downloads the following files:
-
-1. A preprocessed CPE database generated by FleetDM to speed up the translation process: https://github.com/fleetdm/nvd/releases
-2. The historical data for all CVEs and how to match to a CPE: from
- https://nvd.nist.gov/vuln/data-feeds
-
-The database generated in step 1 is processed from the original official CPE dictionary
-https://nvd.nist.gov/products/cpe. This CPE dictionary is typically updated once a day.
-
-The matching occurs server-side to make the processing as fast as possible, but the whole process is both CPU and memory intensive.
-
-For example, when running a development instance of Fleet on an Apple Macbook Pro with 16 cores, matching 200,000 CPEs against the CVE database will take around 10 seconds and consume about 3GBs of RAM.
-
-The CPU and memory usages are in burst once every hour (or the configured periodicity) on the
-instance that does the processing. RAM spikes are expected to not exceed the 2GBs.
-
-### Linux
-
-As with Windows/Mac OS, vulnerability detection for Linux is performed in a single Fleet instance. The
-files downloaded will vary depending on what distributions are on your fleet. The list of all the
-OVAL files we use can be found [here](https://github.com/fleetdm/nvd/blob/master/oval_sources.json).
-
-When determining what specific file(s) to download we use the reported OS version and map that to an
-entry in the `oval_sources.json` dictionary. The mapping rules we use are fairly simple, depending on the
-distribution, we either use the major and minor versions and the platform name (for example `Ubuntu
-22.4.0` -> `ubuntu_2204`) or just the major version (for example `Red Hat Enterprise Linux
-9.0.0` -> `rhel_09`).
-
-To reduce memory footprint during the evaluation phase and because of performance reasons, all downloaded OVAL files are
-parsed, and the result is stored in a file following the following naming convention: `fleet_oval_platform_date.json`.
-
-The performance will be a function of three variables:
-- The size of the OVAL file
-- The amount of hosts to scan
-- The amount of installed software
-
-That said, the performance characteristic should be linear (if scanning 200 hosts take
-~20 seconds, then scanning 2000 hosts should take ~200 seconds).
-
-## Detection pipeline
-
-There are several steps that go into the vulnerability detection process. In this section we'll dive into what they are and how it works.
-
-The process has different parts that are more error-prone than others. Each OS and each application developer and maintainer can (and do) have their own way of defining each part of their app. Some Linux distributions are very strict, but each distribution handles things differently.
-
-The whole pipeline exists to compensate for these differences, and it can be divided in two sections:
-
-1. Collection:
-
- ```mermaid
- graph TD;
- host1[Host1 send software list]-->normalize[Normalization of names, versions, etc]
- host2[Host2 send software list]-->normalize
- host3[Host3 send software list]-->normalize
- normalize-->store[Storage for later processing]
- ```
-
-2. Processing
-
- Processing happens in a loop and varies depending on the platform - first Windows/Mac OS hosts
- will be processed, then we look at Linux hosts. The default interval is 1hr.
-
- ### General process
-
- ```mermaid
- graph TD;
- interval{Once an hour}-->normalize[Normalized software list]
- normalize-->process1[Process Windows/Mac OS hosts]
- process1-->process2[Process Linux hosts]
- process2-->interval
- ```
-
- ### Windows/Mac OS
-
- ```mermaid
- graph TD;
- process[Process Windows/Mac OS hosts] -->downloadCPE(Download CPE database from Fleet)
- downloadCPE-->cpeTranslate[CPE translation]
- cpeTranslate-->cveDownload(CVE datastreams downloaded)
- cveDownload-->cveMap[CVE detection]
- ```
- ### Linux
-
- ```mermaid
- graph TD;
- process[Process Linux hosts] --> fresh{OVAL defs older than one day?}
- fresh --no--> execute(Analyze hosts using OVAL definitions)
- fresh --yes--> remove(Remove old OVAL definitions)
- remove --> download(Download new OVAL definitions)
- download --> parse(Parse OVAL definitions)
- parse --> execute
- ```
-
-### Ingesting software lists from hosts
-
-The ingestion of software varies per platform. We run a `UNION` of several queries in each:
-
-- [macOS](https://github.com/fleetdm/fleet/blob/main/server/service/osquery_utils/queries.go#L315)
-- [Windows](https://github.com/fleetdm/fleet/blob/main/server/service/osquery_utils/queries.go#L478)
-- [Linux](https://github.com/fleetdm/fleet/blob/main/server/service/osquery_utils/queries.go#L391)
-
-This is the first step into normalizing data across platforms, as we try to get all the same data for all different types of software we detect vulnerabilities on.
-
-Ingestion can be resource hungry, both on the hosts and the Fleet server. A lot of work has gone into reducing the resources needed, and it's still ongoing.
-
-### Translating to CPE
-
-With a somewhat normalized list of software, in order to search CVEs for it, we need to derive a [CPE](https://en.wikipedia.org/wiki/Common_Platform_Enumeration) from the vendor, name, version, and OS.
-
-As described briefly above, we do this by translating the NVD database of CPEs into a [sqlite database that helps Fleet do the lookup of CPEs very quickly](https://github.com/fleetdm/nvd).
-
-#### How accurate is this translation process?
-
-This is the most error prone part of the process.
-The CPE can have some vagueness.
-This means that parts of it can be a `*`, which means when you match that CPE to a CVE it can match any of that part of the CPE.
-
-If the CPE is too vague, the extreme case being all parts are `*`, all CVEs will match. You want a very specific CPE, but not too specific that a small error would make it not match a CVE (false negative).
-
-Let's look into some examples of this stage.
-
-##### Example: tmux
-
-tmux is a Unix terminal utility to multiplex ttys. It appears listed like this in macOS:
-
-```
-osquery> SELECT * FROM homebrew_packages WHERE name='tmux';
-+------+----------------------------+---------+
-| name | path | version |
-+------+----------------------------+---------+
-| tmux | /opt/homebrew/Cellar/tmux/ | 3.2a |
-+------+----------------------------+---------+
-```
-
-If we look at the [official releases](https://github.com/tmux/tmux/releases/tag/3.2a) the version we get is the same as the one listed. This means that it'll be easy to map it to a CPE that will accurately represent the software.
-
-Now let's look at Chrome on macOS:
-
-```
-osquery> select name, bundle_version from apps where name like '%Chrome%';
-+-------------------+----------------+
-| name | bundle_version |
-+-------------------+----------------+
-| Google Chrome.app | 4758.102 |
-+-------------------+----------------+
-```
-
-Now things start to get slightly more tricky. We have to remove the `.app` suffix from the name, then derive the first word as the vendor and the second as the app name. We could use `bundle_name` for the app name, but nothing stops the app developer of adding the vendor to `bundle_name`, so a similar parsing would have to happen.
-
-These are two illustrative examples. The reality is that there is no map or list of all the software available and how it's presented in each platform, so the "software to CPE" translation process is going to be evolving constantly.
-
-#### Improving accuracy
-
-In order to improve the accuracy of matching software to CPEs, CPE translations rules are added for known cases where matching fails.
-`server/vulnerabilities/cpe_translations.json` contains these rules and is included in the [NVD release](https://github.com/fleetdm/nvd/releases/latest).
-
-##### Example: `ruby@2.7` installed via `homebrew`
-
-The following CPE translation rule is used to reduce false positives when ruby is installed via homebrew.
-This is needed because ruby is commonly included in the title in the CPE database.
-This rule matches the software name `ruby` matching a regular expression pattern and installed using `homebrew`.
-When searching for CPEs, the specifed `product` and `vendor` will be added to the filter critera.
-
-```
-[
- {
- "software": {
- "name": ["/^ruby(@.*)?$/"],
- "source": ["homebrew_packages"]
- },
- "translation": {
- "product": ["ruby"],
- "vendor": ["ruby-lang"]
- }
- }
-]
-```
-##### Excluding software
-
-If software is mapped to the wrong CPE and it is known that there are no entries for it in the
-NVD dataset, you can specify an exclusion rule by using the `skip` field. If the rule matches, the
-software will be excluded from the NVD vulnerability scanning process and, **no NVD vulnerabilities**
-will be reported.
-
-```
-{
- "software": {
- "name": ["Docs"],
- "source": ["chrome_extensions"]
- },
- "filter": {
- "skip": true
- }
- }
-```
-
-##### CPE Translations (array[CPE Translation Entry])
-
-##### CPE Translation Entry (object)
-
-The CPE translation rule.
-
-| Name | Type | Description |
-| --- | --- | --- |
-| `software` | array[CPE Translation Software] | The CPE translation software match criteria. |
-| `translation` | array[CPE Translation] | The CPE translation. |
-
-##### CPE Translation Software (object)
-
-The CPE translation software match criteria. Used to match software collected from hosts. Fields are are AND'd together. Values inside each field are OR'd together.
-
-| Name | Type | Description |
-| --- | --- | --- |
-| `name` | array[string] | The software name to match. Enclose within `/` to specify a regular expression pattern. |
-| `bundle_identifer` | array[string] | The software bundle identifier (MacOS apps only) to match. Enclose within `/` to specify a regular expression pattern. |
-| `source` | array[string] | The software source to match. Enclose within `/` to specify a regular expression pattern. |
-
-##### CPE Translation (object)
-
-The CPE translation. Used to match CPEs in the CPE database. Fields are are AND'd together. Values inside each field are OR'd together.
-
-| Name | Type | Description |
-| --- | --- | --- |
-| `product` | array[string] | The CPE product. |
-| `vendor` | array[string] | The CPE vendor. |
-| `target_sw` | array[string] | The CPE target software. |
-| `skip` | bool | If true, matched software will be skipped from the NVD vulnerability scanning process |
-
-### Matching a CPE to a CVE
-
-Once we have a good CPE, we can match it against the CVE database. We download the data streams locally and match each CPE to the whole list. The matching is done using the [nvdtools implementation](https://github.com/facebookincubator/nvdtools).
-
-
diff --git a/docs/Using-Fleet/configuration-files/README.md b/docs/Using-Fleet/configuration-files/README.md
deleted file mode 100644
index 092d0a7e6..000000000
--- a/docs/Using-Fleet/configuration-files/README.md
+++ /dev/null
@@ -1,1457 +0,0 @@
-# Configuration files
-
-- [Queries](#queries)
-- [Labels](#labels)
-- [Enroll secrets](#enroll-secrets)
- - [Multiple enroll secrets](#multiple-enroll-secrets)
- - [Rotating enroll secrets](#rotating-enroll-secrets)
-- [Teams](#teams)
- - [Team agent options](#team-agent-options)
- - [Team enroll secrets](#team-enroll-secrets)
- - [Mobile device management settings for teams](#mobile-device-management-mdm-settings-for-teams)
-- [Organization settings](#organization-settings)
-
-Fleet can be managed with configuration files (YAML syntax) and the fleetctl command line tool. This page tells you how to write these configuration files.
-
-Changes are applied to Fleet when the configuration file is applied using fleetctl. Check out the [fleetctl documentation](https://fleetdm.com/docs/using-fleet/fleetctl-cli#using-fleetctl-to-configure-fleet) to learn how to apply configuration files.
-
-## Queries
-
-The `query` YAML file controls queries in Fleet.
-
-You can define one or more queries in the same file with `---`.
-
-The following example file includes several queries:
-
-```yaml
----
-apiVersion: v1
-kind: query
-spec:
- name: osquery_schedule
- description: Report performance stats for each file in the query schedule.
- query: select name, interval, executions, output_size, wall_time, (user_time/executions) as avg_user_time, (system_time/executions) as avg_system_time, average_memory, last_executed from osquery_schedule;
----
-apiVersion: v1
-kind: query
-spec:
- name: osquery_info
- description: A heartbeat counter that reports general performance (CPU, memory) and version.
- query: select i.*, p.resident_size, p.user_time, p.system_time, time.minutes as counter from osquery_info i, processes p, time where p.pid = i.pid;
----
-apiVersion: v1
-kind: query
-spec:
- name: osquery_events
- description: Report event publisher health and track event counters.
- query: select name, publisher, type, subscriptions, events, active from osquery_events;
-```
-
-Continued edits and applications to this file will update the queries.
-
-If you want to change the name of a query, you must first create a new query with the new name and then delete the query with the old name.
-
-## Labels
-
-The following file describes the labels which hosts should be automatically grouped into. The label resource should include the actual SQL query so that the label is self-contained:
-
-```yaml
-apiVersion: v1
-kind: label
-spec:
- name: slack_not_running
- query: >
- SELECT * FROM system_info
- WHERE NOT EXISTS (
- SELECT *
- FROM processes
- WHERE name LIKE "%Slack%"
- );
-```
-
-Labels can also be "manually managed". When defining the label, reference hosts
-by hostname:
-
-```yaml
-apiVersion: v1
-kind: label
-spec:
- name: Manually Managed Example
- label_membership_type: manual
- hosts:
- - hostname1
- - hostname2
- - hostname3
-```
-
-## Enroll secrets
-
-The following file shows how to configure enroll secrets. Enroll secrets are valid until you delete them.
-
-```yaml
-apiVersion: v1
-kind: enroll_secret
-spec:
- secrets:
- - secret: RzTlxPvugG4o4O5IKS/HqEDJUmI1hwBoffff
- - secret: YBh0n4pvRplKyWiowv9bf3zp6BBOJ13O
-```
-
-Osquery provides the enroll secret only during the enrollment process. Once a host is enrolled, the node key it receives remains valid for authentication independent from the enroll secret.
-
-Currently enrolled hosts do not necessarily need enroll secrets updated, as the existing enrollment will continue to be valid as long as the host is not deleted from Fleet and the osquery store on the host remains valid. Any newly enrolling hosts must have the new secret.
-
-Deploying a new enroll secret cannot be done centrally from Fleet.
-
-Osquery provides the enroll secret only during the enrollment process. Once a host is enrolled, the node key it receives remains valid for authentication independent from the enroll secret.
-
-Currently enrolled hosts do not necessarily need enroll secrets updated, as the existing enrollment will continue to be valid as long as the host is not deleted from Fleet and the osquery store on the host remains valid. Any newly enrolling hosts must have the new secret.
-
-Deploying a new enroll secret cannot be done centrally from Fleet.
-
-### Multiple enroll secrets
-
-Fleet allows the abiility to maintain multiple enroll secrets. Some organizations have internal goals around rotating secrets. Having multiple secrets allows some of them to work at the same time the rotation is happening.
-Another reason you might want to use multiple enroll secrets is to use a certain [team enroll secret](#team-enroll-secrets) to auto-enroll hosts into a specific [team](https://fleetdm.com/docs/using-fleet/teams) (Fleet Premium).
-
-### Rotating enroll secrets
-
-Rotating enroll secrets follows this process:
-
-1. Add a new secret.
-2. Transition existing clients to the new secret. Note that existing clients may not need to be
- updated, as the enroll secret is not used by already enrolled clients.
-3. Remove the old secret.
-
-To do this with `fleetctl` (assuming the existing secret is `oldsecret` and the new secret is `newsecret`):
-
-Begin by retrieving the existing secret configuration:
-
-```
-$ fleetctl get enroll_secret
----
-apiVersion: v1
-kind: enroll_secret
-spec:
- secrets:
- - created_at: "2021-11-17T00:39:50Z"
- secret: oldsecret
-```
-
-Apply the new configuration with both secrets:
-
-```
-$ echo '
----
-apiVersion: v1
-kind: enroll_secret
-spec:
- secrets:
- - created_at: "2021-11-17T00:39:50Z"
- secret: oldsecret
- - secret: newsecret
-' > secrets.yml
-$ fleetctl apply -f secrets.yml
-```
-
-Now transition clients to using only the new secret. When the transition is completed, remove the
-old secret:
-
-```
-$ echo '
----
-apiVersion: v1
-kind: enroll_secret
-spec:
- secrets:
- - secret: newsecret
-' > secrets.yml
-$ fleetctl apply -f secrets.yml
-```
-
-At this point, the old secret will no longer be accepted for new enrollments and the rotation is
-complete.
-
-A similar process may be followed for rotating team-specific enroll secrets. For teams, the secrets
-are managed in the team yaml.
-
-## Teams
-
-**Applies only to Fleet Premium**.
-
-The `team` YAML file controls a team in Fleet.
-
-You can define one or more teams in the same file with `---`.
-
-The following example file includes one team:
-
-```yaml
-apiVersion: v1
-kind: team
-spec:
- team:
- name: Client Platform Engineering
- features:
- enable_host_users: false
- enable_software_inventory: true
- additional_queries:
- time: SELECT * FROM time
- macs: SELECT mac FROM interface_details
- agent_options:
- config:
- decorators:
- load:
- - SELECT uuid AS host_uuid FROM system_info;
- - SELECT hostname AS hostname FROM system_info;
- options:
- disable_distributed: false
- distributed_interval: 10
- distributed_plugin: tls
- distributed_tls_max_attempts: 3
- logger_tls_endpoint: /api/v1/osquery/log
- logger_tls_period: 10
- pack_delimiter: /
- overrides: {}
- command_line_flags: {}
- secrets:
- - secret: RzTlxPvugG4o4O5IKS/HqEDJUmI1hwBoffff
- - secret: JZ/C/Z7ucq22dt/zjx2kEuDBN0iLjqfz
- mdm:
- macos_updates:
- minimum_version: "12.3.1"
- deadline: "2022-01-04"
- macos_settings:
- custom_settings:
- - path/to/profile1.mobileconfig
- - path/to/profile2.mobileconfig
- enable_disk_encryption: true
-```
-
-### Team agent options
-
-The team agent options specify options that only apply to this team. When team-specific agent options have been specified, the agent options specified at the organization level are ignored for this team.
-
-The documentation for this section is identical to the [Agent options](#agent-options) documentation for the organization settings, except that the YAML section where it is set must be as follows. (Note the `kind: team` key and the location of the `agent_options` key under `team` must have a `name` key to identify the team to configure.)
-
-```yaml
-apiVersion: v1
-kind: team
-spec:
- team:
- name: Client Platform Engineering
- agent_options:
- # the team-specific options go here
-```
-
-### Team secrets
-
-The `secrets` section provides the list of enroll secrets that will be valid for this team. If the section is missing, the existing secrets are left unmodified. Otherwise, they are replaced with this list of secrets for this team.
-
-- Optional setting (array of dictionaries)
-- Default value: none (empty)
-- Config file format:
- ```
- team:
- name: Client Platform Engineering
- secrets:
- - secret: RzTlxPvugG4o4O5IKS/HqEDJUmI1hwBoffff
- - secret: JZ/C/Z7ucq22dt/zjx2kEuDBN0iLjqfz
- ```
-
-### Modify an existing team
-
-You can modify an existing team by applying a new team configuration file with the same `name` as an existing team. The new team configuration will completely replace the previous configuration. In order to avoid overiding existing settings, we reccomend retreiving the existing configuration and modifying it.
-
-Retrieve the team configuration and output to a YAML file:
-
-```console
-% fleetctl get teams --name Workstations --yaml > workstation_config.yml
-```
-After updating the generated YAML, apply the changes:
-
-```console
-% fleetctl apply -f workstation_config.yml
-```
-
-Depending on your Fleet version, you may see `unsupported key` errors for the following keys when applying the new team configuration:
-
-```
-id
-user_count
-host_count
-integrations
-webhook_settings
-description
-agent_options
-created_at
-user_count
-host_count
-integrations
-webhook_settings
-```
-
-You can bypass these errors by removing the key from your YAML or adding the `--force` flag. This flag will force application of the changes without validation. Proceed with caution.
-
-### Mobile device management (MDM) settings for teams
-
-> MDM features are not ready for production and are currently in development. These features are disabled by default.
-
-The `mdm` section of this configuration YAML lets you control MDM settings for each team in Fleet.
-
-To specify Team MDM configuration, as opposed to [Organization-wide MDM configuration](#mobile-device-management-mdm-settings), follow the below YAML format. Note the `kind: team` field, as well as the `name` and `mdm` fields under `team`.
-
-```yaml
-apiVersion: v1
-kind: team
-spec:
- team:
- name: Client Platform Engineering
- mdm:
- # the team-specific mdm options go here
-```
-
-## Organization settings
-
-The `config` YAML file controls Fleet's organization settings and MDM features for hosts assigned to "No team."
-
-The following example file shows the default organization settings:
-
-```yaml
-apiVersion: v1
-kind: config
-spec:
- agent_options:
- config:
- decorators:
- load:
- - SELECT uuid AS host_uuid FROM system_info;
- - SELECT hostname AS hostname FROM system_info;
- options:
- disable_distributed: false
- distributed_interval: 10
- distributed_plugin: tls
- distributed_tls_max_attempts: 3
- logger_tls_endpoint: /api/osquery/log
- logger_tls_period: 10
- pack_delimiter: /
- overrides: {}
- command_line_flags: {}
- features:
- enable_host_users: true
- enable_software_inventory: true
- fleet_desktop:
- transparency_url: https://fleetdm.com/transparency
- host_expiry_settings:
- host_expiry_enabled: false
- host_expiry_window: 0
- integrations:
- jira: null
- zendesk: null
- org_info:
- org_logo_url: ""
- org_name: Fleet
- server_settings:
- deferred_save_host: false
- enable_analytics: true
- live_query_disabled: false
- server_url: ""
- smtp_settings:
- authentication_method: authmethod_plain
- authentication_type: authtype_username_password
- domain: ""
- enable_smtp: false
- enable_ssl_tls: true
- enable_start_tls: true
- password: ""
- port: 587
- sender_address: ""
- server: ""
- user_name: ""
- verify_ssl_certs: true
- sso_settings:
- enable_jit_provisioning: false
- enable_sso: false
- enable_sso_idp_login: false
- entity_id: ""
- idp_image_url: ""
- idp_name: ""
- issuer_uri: ""
- metadata: ""
- metadata_url: ""
- vulnerabilities:
- databases_path: "/tmp/vulndbs"
- periodicity: 1h
- cpe_database_url: ""
- cpe_translations_url: ""
- cve_feed_prefix_url: ""
- current_instance_checks: "auto"
- disable_data_sync: false
- recent_vulnerability_max_age: 30d
- disable_win_os_vulnerabilities: false
- webhook_settings:
- failing_policies_webhook:
- destination_url: ""
- enable_failing_policies_webhook: false
- host_batch_size: 0
- policy_ids: null
- host_status_webhook:
- days_count: 0
- destination_url: ""
- enable_host_status_webhook: false
- host_percentage: 0
- interval: 24h
- vulnerabilities_webhook:
- destination_url: ""
- enable_vulnerabilities_webhook: false
- host_batch_size: 0
- mdm:
- apple_bm_default_team: ""
- macos_updates:
- minimum_version: ""
- deadline: ""
- macos_settings:
- custom_settings:
- - path/to/profile1.mobileconfig
- - path/to/profile2.mobileconfig
- enable_disk_encryption: true
-```
-
-### Settings
-
-All possible settings are organized below by section.
-
-Each section's key must be one level below the `spec` key, indented with spaces (not `
-
-
-
-### Available commands
-
-Much of the functionality available in the Fleet UI is also available in `fleetctl`. You can run queries, add and remove users, generate agent (fleetd) installers to add new hosts, get information about existing hosts, and more!
-
-To see the commands you can run with fleetctl, run the `fleetctl --help` command.
-
-### Get more info about a command
-
-Each command available to `fleetctl` has a help menu with additional information. To pull up the help menu, run `fleetctl